Introducing Nearmap for Post-catastrophe Response
Post Catastrophe Imagery and AI-derived property damage and condition data unite to help insurers process customer claims more efficiently.
Post Catastrophe Imagery and AI-derived property damage and condition data unite to help insurers process customer claims more efficiently.
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 API development.
We recently released a new version of our Tile API, which you can find documented here. In this post, I’d like to 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:
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:
Our new APIs encapsulate all of these requirements in a compact and easy-to-understand fashion:
Beginning with the Tile API, we are adopting the above URL format for all our future APIs. Our eventual goal is to move users from the existing APIs onto the new ones, and we will work with our customers over the coming months to ensure a smooth transition.
You may be wondering why we decided to go with a new API, rather than making gradual improvements to the existing API. 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:
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.
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.
I find the topic of backward compatibility and unintended consequences of undocumented usage fascinating. 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.”
Whilst our backward compatibility efforts pale in comparison to the above SimCity example, we analyse 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 behaviour.
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 changing the TMS endpoint from au0.nearmap.com to autiles0.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 we made 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 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: igor.zevaka@nearmap.com.
