Products

Solutions

Resources

Get a Demo

Aerial map APIs - the Nearmap path forward

Jan 2019
Nearmap API’s provide new improvements in one release. Learn how it can make project planning easier with simple exporting of aerial mapping imagery.
Jan 2019
hero-image

In this three-part series, we introduce the new Nearmap APIs, talk about use cases and intended usage, and lay out the roadmap for future Nearmap API development.

We recently released a new version of our Tile API, which you can find documented here. In this post, let’s introduce this new protocol and provide additional background on some of our design decisions.
The first version of the Nearmap Tile API was published in 2010, and we’ve maintained it since then. We know that our customers rely on Nearmap for their critical applications, so we maintain backward compatibility for all our published APIs (and sometimes even for non-published ones).
That said, a lot of things have changed at Nearmap since 2010:
  • Business Model: successfully created a new “location content as a service” market
  • Reach: grew our customer base to over 8,000 unique accounts
  • Coverage: flew many more surveys globally, increasing our aggregate coverage ten-fold
  • Expansion: ventured beyond our flagship market, Australia, to the U.S. and New Zealand
  • Integration: helped hundreds of customers across many industries create apps that consume our content
With everything at Nearmap maturing – our processes, our business model, our sales and engineering teams – it’s time to turn our attention to our APIs and make sure that they evolve with the rest of the business. With that in mind, we set out to design “the perfect API” and came up with the following five design principles:
  • Global: Consume any content through one endpoint, without worrying about separate domains
  • Namespaced: Different APIs “live” in different places, allowing us to implement changes as needed
  • Consistent: All our published APIs “look and smell” the same
  • Versioned: We can release new versions of the API without breaking existing applications
  • Secure: APIs enforce security best practices, including mandatory HTTPS

The new Tile API

Our new APIs encapsulate all of these requirements in a compact and easy-to-understand way:
  • HTTPS: The new API is only supported on HTTPS.
  • New API domain: api.nearmap.com is a global endpoint that will direct users to the most optimal server.
  • Each API “family” has its own namespace: Tile, WMS, WMTS, Coverage, etc.
  • API Version: now explicit in the naming schema.
Beginning with the Tile API, we are adopting the above URL format for all our future APIs. Our goal is to eventually move users from the existing APIs to the new ones, and we will work with our customers over the coming months to ensure a smooth transition.

Why a completely new API?

You may be wondering why we decided to go with a new API, rather than making gradual improvements to the existing one. The decision was influenced by a combination of many things and an explicit decision to batch all the breaking changes into one release so that our customers only have to make one change to benefit from all the new features.
Here are some of the improvements you can expect with the new API:
  • New URL format as per above. Changes to URLs are automatically breaking.
  • HTTPS only. This is where the web is heading.
  • Removal of insecure authentication methods. Only API Key Authentication is supported.
  • Better defaults. In particular, the default version of the TMS API is subject to what’s internally known as a “time travel bug.” More on that in later posts.
  • More available metadata. This is relevant to the Coverage API, which is replacing the INFO call API; the existing JSON structure simply didn’t support additional information being returned.
  • Cleaner HTTP response codes.
  • Better support for automated workflows.
We bundled all of the above improvements into one release, and are now making it available to new and existing customers in parallel with the legacy API. We will be repeating this pattern for other APIs in due time, which I’ll cover in future posts.
In addition to offering a cleaner, more intuitive experience for our customers, the new Tile API also offers significant benefits for Nearmap’s partner organizations. Nearmap product manager Tom Bass had this to say about the changes. “The new Tile API provides richer metadata so that it’s easier for interactive platform partners to call down imagery for a specific area, at a specific resolution, and for a specific survey,” Bass said. “This will have an enduring positive impact as we continue to expand our partner program.”

Backward Compatibility

As a provider of HTTP(S) APIs, we are acutely of aware of maintaining backward compatibility for our integrations. An API, by definition Application Programming Interface, is a contact point between Nearmap and our customer’s application. Any changes to the interface, even if they are fixes or improvements, may result in that application not being able to load Nearmap content. As such, we are focused on ensuring that our published APIs continue to work as expected. We run in excess of 5,000 automated checks daily, in addition to manual regression tests, to ensure that new developments do not break compatibility.
This is pretty much a full time job for the API team at Nearmap. Many tech companies do the same, and you can find the best examples from Microsoft, especially by Raymond Chan. In the early days of Windows, Microsoft went to extraordinary lengths to maintain compatibility. Here’s an interesting story from Joel Spolsky, formerly of Microsoft. You may know Joel these days from StackOverflow, Trello, and the most incredible Excel training video.
According to Spolsky,“I first heard about this from one of the developers of the hit game SimCity, who told me that there was a critical bug in his application: it used memory right after freeing it, a major no-no that happened to work OK on DOS but would not work under Windows where memory that is freed is likely to be snatched up by another running application right away. The testers on the Windows team were going through various popular applications, testing them to make sure they worked OK, but SimCity kept crashing. They reported this to the Windows developers, who disassembled SimCity, stepped through it in a debugger, found the bug, and added special code that checked if SimCity was running, and if it did, ran the memory allocator in a special mode in which you could still use memory after freeing it.”
While our backward compatibility efforts pale in comparison to the above SimCity example, we analyze seemingly innocuous changes for potential impacts to customer applications for every release. One of the more interesting fixes we implemented was allowing “wrapping” of tile x/y coordinates on our legacy API as we detected that some customers relied on this undocumented behavior.
So, we maintain backward compatibility for existing APIs, but what if we want to introduce breaking changes because the existing APIs are suboptimal?
A breaking change, in our case, is a modification to the API that requires applications to make a corresponding change to continue working. An example of such a change would be converting the TMS endpoint from us0.nearmap.com to ustiles0.nearmap.com and turning off the original endpoint. If we were to do this, hundreds, if not thousands, of applications would stop working overnight.
In order to avoid this kind of disruption, we are releasing the new API and running the old API in parallel. This allows new customers to start using the new API and gives us time to transition existing customers onto the new API. As you can see from the documentation, the now-legacy API is still supported, with a note that it’s now deprecated. We will publish a deprecation schedule early in 2019 and will kick off migration activities then.
The next post in this series will talk about the features available in the new version of the Tile API, and how you can use those to improve your application.
Igor Zevaka is the product manager for Nearmap’s content APIs. With a degree in software engineering from the University of Technology Sydney, 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.