Map Coordinates

Map a set of coordinates to a geographical region.

The Map Coordinates API allows you to map a latitude and longitude position to a location. You can find the location as a country, a timezone, or a US zipcode.

Quick Start

The Map Coordinates API has three required parameters, lat, lon, and targets.

The lat and lon parameters specify the latitude and longitude coordinates of the location that you want to find. The latitude value is between -90 and 90, where negative values represent locations in the southern hemisphere. The longitude value is between -180 and 180, where negative values represent locations West of the Greenwich meridian.

The targets parameter specifies what information to find about the specified coordinates. You can return the location country, the timezone, or the zipcode for locations in the US. You can specify multiple target types.

/1/api/[sync|async]/mapcoordinates/v1?lat=52.2&lon=0.122&targets=country&targets=timezone

The API returns the target information, along with additional information about the target.

Synchronous
https://api.havenondemand.com/1/api/sync/mapcoordinates/v1
Asynchronous
https://api.havenondemand.com/1/api/async/mapcoordinates/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
targets
array<enum> The type of geographical region to map the latitude and longitude coordinates to.
lat
number The latitude coordinate to locate. This value must be between -90 and 90.
lon
number The longitude coordinate to locate. This value must be between -180 and 180.
Enumeration Types

This API's parameters use the enumerations described below:

targets
The type of geographical region to map the latitude and longitude coordinates to.
country Countries
Maps a latitude and longitude to a country.
timezone UTC Timezones
Maps a latitude and longitude to a timezone.
zipcode_us US Zipcodes
Maps a latitude and longitude to a US zipcode.

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Map Coordinates Response {
matches ( array[Matches] ) The details of the returned matches.
}
Map Coordinates Response:Matches {
name ( string ) The name of the match.
target ( enum<Target> ) The matched location target.
additional_information ( Additional_information , optional)
}
enum<Map Coordinates Response:Matches:Target> {
'country' , 'timezone' , 'zipcode_us'
}
Map Coordinates Response:Matches:Additional_information {
wikidata_id ( number , optional) The Wikidata ID related to the match. Applies only to the country target type.
wikipedia_eng ( string , optional) The URL of a Wikipedia page related to the match. Applies only to the country target type.
image ( string , optional) The URL for an image related to the match on Wikipedia commons. Applies only to the country target type.
place_country_code ( string , optional) The country code of the match. Applies only to the country and zipcode_us target types.
place_region1 ( string , optional) The top level region of the match. Applies only to the country and zipcode_us target types.
place_region2 ( string , optional) The second level region of the match. Applies only to the zipcode_us target type, where it contains the county.
place_location ( string , optional) The location of the match. Applies only to the timezone and zipcode_us target types.
place_timezone ( number , optional) The UTC timezone of the match. Applies only to the timezone target type.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "targettype": {
        "enum": [
            "country",
            "timezone",
            "zipcode_us"
        ]
    },
    "properties": {
        "matches": {
            "items": {
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "target": {
                        "$ref": "#/targettype"
                    },
                    "additional_information": {
                        "properties": {
                            "wikidata_id": {
                                "type": "number"
                            },
                            "wikipedia_eng": {
                                "type": "string"
                            },
                            "image": {
                                "type": "string"
                            },
                            "place_country_code": {
                                "type": "string"
                            },
                            "place_region1": {
                                "type": "string"
                            },
                            "place_region2": {
                                "type": "string"
                            },
                            "place_location": {
                                "type": "string"
                            },
                            "place_timezone": {
                                "type": "number"
                            }
                        },
                        "type": "object"
                    }
                },
                "required": [
                    "name",
                    "target"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "matches"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/sync/mapcoordinates/v1
/api/api-example/1/api/sync/mapcoordinates/v1
Examples
See this API for yourself - select one of our examples below.
Country search
Get the country for coordinates 39.90° N, 116.40° E (Beijing)
Zipcode search
Get the zipcode for coordinates 42.37° N, 71.10° W (Cambridge, MA)
Country and timezone search
Get the country and timezone for coordinates 37.44° N, 122.14° W (Palo Alto)
Parameters
Required
Name Type Value
targets
array
lat
number
lon
number


ASync – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.