This sections provides an example API project, where GeoSports uses Nearmap APIs to write an image download script.

GeoSports is a (fictional) community organization that uses Nearmap imagery to monitor the condition of sports fields in locations around California. GeoSports has a KML file containing the locations of each field they are interested in, stored as polygons. This KML file can be loaded in Google Earth or the Nearmap MapBrowser, like this:

You can download our sample KML here. 

The GeoSports software team will write a script to download a Nearmap image of each sports field, for each date that Nearmap has captured it. The team will use the documented Nearmap APIs to write their script.

Part 1: Authentication

The GeoSports team consults the Nearmap documentation on API Key Authentication.

Firstly, the GeoSports Nearmap administrator logs in to https://admin.nearmap.com/welcome/ and continues until the screen with the option of "My API Keys" is displayed. The admin then creates an API Application called "GeoSports Field Application".

The GeoSports team have a Nearmap user account, api@geosports.com, which they use for all their integrations to Nearmap imagery. One of the team logs in to https://admin.nearmap.com/welcome/ as that user and creates an API Key on the "GeoSports Field Application" API Application. The resulting API Key is a long string of characters. The team will include this API Key in all their API calls. 

Part 2: Retrieve a List of Available Imagery Dates for a Location

For this step, the GeoSports team uses Nearmap API documentation on retrieving a list of available surveys for a location. 

From their KML file, the GeoSports team works out the latitude and longitude coordinates for the center of each area for which they want to download imagery.

Here's an example polygon from the sample KML attached to this page:

The latitude of the center of this polygon is:

37.867892 + ((37.870445 - 37.867892) /2) = 37.8691685

The longitude of the center of this polygon is:

-122.263826 - ((122.265912 - 122.263826) / 2) = -122.264869

Therefore, the center point of this polygon is 37.8691685,-122.264869. 

The script can now query for a list of dates for which imagery is available for that location. The GeoSports team uses the nmq=INFO parameter to retrieve a list of available survey dates for a location. Here's the request:

https://us0.nearmap.com/maps?ll=37.8691685,-122.264869&nmq=INFO&nmf=json&zoom=18&httpauth=false&apikey=YOUR_API_KEY

And here's the JSON response:

{
  "layers":{
    "Dem_":[
      "\/Date(1409443200000)\/",
      "\/Date(1424736000000)\/",
      "\/Date(1441756800000)\/",
      "\/Date(1446163200000)\/"],
    "Dsm_":[
      "\/Date(1409443200000)\/",
      "\/Date(1424736000000)\/",
      "\/Date(1441756800000)\/",
      "\/Date(1446163200000)\/"],
    "Vert":[
      "\/Date(1409443200000)\/",
      "\/Date(1424736000000)\/",
      "\/Date(1441756800000)\/",
      "\/Date(1446163200000)\/"]}, 
   "within_allowed_area":1, 
   "coverage_status": "full", 
   "area_type": null 
}

The script extracts a list of dates where vertical imagery is available. This information comes from the "Vert" list in the JSON response above.

Here's the "Vert" list:

"Vert":["\/Date(1409443200000)\/","\/Date(1424736000000)\/","\/Date(1441756800000)\/","\/Date(1446163200000)\/"]

The available imagery dates are in ASP.NET AJAX date format. The GeoSports team must include in their script a conversion of the list of dates to YYYYMMDD format:

1409443200000 => 20140631
1424736000000 => 20150224
1441756800000 => 20150909
1446163200000 => 20151030

Part 3: Retrieve Imagery for a Specified Date and Location

With the date format converted, the script passes the date parameters and bounding box coordinates for each area of interest to the Nearmap API for retrieving imagery by date and bounding box. 

Here's an example URL request:

http://us.nearmap.com/staticmap?bbox=37.867892,-122.265912,37.870445,-122.263826&zoom=18&date=20140631&httpauth=false&apikey=YOUR_API_KEY

Considerations

When writing their script, here are some important points the GeoSports team will need to consider:

• All imagery requests and image metadata requests (i.e. requests for imagery dates) must include the API Key.
• It’s possible that different sets of imagery dates might be available for different areas within one bounding box, if that bounding box spans more than one survey.
• The team should become familiar with how the Nearmap API responds when no imagery for a specified date is available.