7 Workflows for image integrations and APIs
Jan 2019
The Nearmap Coverage API is structured in a way that allows us to simply plug in new types of spatial content support this catalogue expansion.
Jan 2019
)
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:
- By area: We have users in Australia, the United States, and New Zealand
- By feature: e.g. content type, such as Vertical or Panorama tiles
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:
- Survey ID
- Survey location: capture region, state, e.g. US, MA, Boston
- Survey GSD
- First and last photo timestamps
- Time zone of the survey
- Offset from UTC (to convert timestamps into local time)
- Max scale of the tile resource
- Time the survey went online
With more attributes available, application developers can do much more:
- Inspect the pixelSize attribute and, with post-processing, show only high resolution surveys.
- Inspect first and last photo time attributes and estimate the time period over which the survey was captured (e.g. to favour morning, midday, or afternoon captures). Note that all Nearmap captures are done at minimum 30º sun elevation angle.
- Inspect the location metadata and distinguish between different capture regions, e.g. Sydney, Wollongong, Gold Coast.
- Inspect the max zoom scale for a survey and adjust the application to disallow presenting surveys beyond the resolution they were captured at. You can think of overzooming as a “digital zoom” where the picture looks bigger, but without any additional detail.
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.
Tile API
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.
Default
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.
)
tertiary=satellite
)
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.
Default (latest)
)
Explicit survey
)
Mosaicking order
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:
Before demolition
Parameter
Value
Result
since
<not specified>
Imagery from May 5 2015 is shown
until
2015-06-10
mosaic
<not specified>
)
Post-demolition
Parameter
Value
Result
since
2015-06-10
Imagery from July 4 2015 is shown
until
<not specified>
mosaic
earliest
)
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:
- 2-3 Years (since=3Y&until=2Y)
- 1-2 Years (since=2Y&until=1Y)
- 6 Months (since=1Y&until=6M)
- Latest (since=6M)
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 Nearmap Product Manager for 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 the Nearmaps API suite. Feel free to drop Igor a line: igor.zevaka@nearmap.com.