In the first post in this series, I introduced our new approach to the Nearmap APIs. In this post, I’ll take you through the new features of the Coverage API and the Tile API, and show you examples of what your application can do with the extensive library of Nearmap content.
The deprecated Nearmap INFO API (what is now known as Coverage API) was designed to support simple 2D maps. As we make new content types available — starting with source obliques and eventually moving to 3D — we are realising that we need a new structure to support this catalogue expansion. The new Coverage API is structured in a way that allows us to simply plug in new types of spatial content.
At this stage, we are not making any new content types available through the APIs, and we're only exposing Vertical and Panorama tiles. As we make any new and exciting API releases, they will supplement the existing Coverage API without requiring major changes in client applications. Our intention is to make the Coverage API a “restaurant menu” of all our content, where you request an area and we respond with a detailed list of available content types with dates.
While we were at it, we also added some additional features to enable the creation of more compelling applications. Here’s a summary of the upgrades:
Requesting metadata with a bounding polygon
We realise that our customers have different workflows, and sometimes they’re interested in more than just being able to request a list of dates for a specific latitude/longitude.
You can now list surveys for any arbitrary shape — a rectangle, a polygon, or even a unicorn (if you're into GPS art). With this request method, you can, for example, send a polygon describing a residential parcel and receive back all surveys that cover that parcel.
Syncing up with user permissions
The Coverage API now takes into account user permissions. There are two ways in which Nearmap content can be controlled depending on the customer's product:
The Coverage API takes all the permissions into account, allowing applications to make more intelligent choices about a user's access level. We have a number of partners, such as Roofsnap and Aurora Solar, who allow their customers to use their Nearmap API key to bring Nearmap content into the partner's application. By calling the Coverage API on behalf of the user, these applications are able to customise the experience for users, who, for example, don't have access to a particular geographic area.
No more tertiary surveys
You may have noticed that in our MapBrowser web interface, we show a satellite backdrop for the whole world. That imagery comes from a set of 2004 NASA satellite surveys (called Blue Marble) and we used to include a few of those surveys through our old INFO call API.
As most of our users are interested in up-to-date, high resolution imagery, we found those Blue Marble dates to be counterproductive, causing confusion. These are now removed from the API, making sure that any dates you get are high resolution Nearmap surveys.
More metadata attributes
We are now making more metadata about our surveys available. Here’s a full list:
Sorting and limiting response attributes
With more metadata available through the API, we also added ways to reduce the results to minimise response times and processing on the client side. You can read more about fields and sort parameters in our documentation.
Explicit blending with tertiary imagery
Applications may choose to show just Nearmap imagery or, if zooming out to the whole world is required, allow blending with satellite images. Coupled with the automatic response type (.img), this is useful in automated consumption scenarios where the application can detect partial images by looking at the content type. By turning off the satellite imagery, you can add a Nearmap tile layer to an off-the-shelf application (such as QGIS or GeoCortex), which will overlay our imagery on your own satellite or thematic basemap.
Based on customer feedback, we are now making "just" Nearmap imagery the default. If you make tile requests with minimal request parameters, you will get only Nearmap imagery without the satellite background.
Request tiles for an explicit survey
This is a new mode of accessing tiles where instead of specifying dates, you can request tiles for an explicit survey ID (which you can retrieve from the Coverage API). This allows applications greater control over returned imagery by ensuring that only one survey is rendered at a time. I envisage this feature will be used by custom applications, especially when the images are consumed in an automated fashion.
This is a brand new feature to reverse the order in which the captures are prioritised for display. By overriding the default latest-on-top semantics, applications may chose to prioritise the earliest captures. This is most useful with the since parameter, and allows users to retrieve imagery on or after a specified date.
Since and until parameters
Until now, the Tile API only accepted one date parameter, effectively returning the latest imagery on or before that date. This works reasonably well considering that most users want to use the latest imagery. We have now added another date parameter, since, that limits how early the imagery can be. When the since parameter is coupled with the mosaic parameter, you can create a map that shows imagery that is captured on or after a specified date. In some scenarios this will allow a more natural configuration of layers.
For example, let’s imagine we have an ArcGIS Online map (which you can integrate with the Tile API) that tracks the NorthConnex tunnel construction (view in MapBrowser). We know that the demolition started sometime in June 2015. Using one date, we can create two layers — just before and just after demolition began:
This scenario was possible but awkward with the previous version of the API. In the old version, you would go to MapBrowser, scroll through the dates, and pull out the dates for the surveys before and after the demolition started, and then configure two layers with those dates. The difference is subtle, but it allows you to only worry about the date that you know, not the dates of Nearmap surveys.
Relative date requests
We made changes to the date parameter syntax and are now accepting only dates formatted using ISO 8601, e.g. 2018-09-17. Additionally, we now allow relative date specification. For example, "since=12M&until=6M" will return imagery between six and 12 months ago. This allows applications to configure layers that look something like this:
These layers only need to be configured once, and they will always return the imagery within these intervals. Such a setup may be appropriate in some compliance workflows that provide the user with an option to quickly bring up a basemap of preset times. Note that all the layers have a since parameter to reduce confusion. This ensures that if no captures exist in the specified period, no imagery is shown.
In our next post, I’ll talk about the security features of the new APIs we added to ensure that your communication with Nearmap servers is confidential.
Igor Zevaka is the product manager for Nearmap’s content APIs. With a degree in software engineering from UTS, Igor creates new APIs to support emerging location content products. He is passionate about discovering new customer use cases to create fresh ways of accessing location content with Nearmap’s API suite. Feel free to drop Igor a line: firstname.lastname@example.org.