Getting Access

Accessing endpoints on the MapAnything API Platform requires a valid API key associated with your account, and all clients must obtain authentication credentials prior to having access to MapAnything API’s. Your API key is provided via the request header using the x-api-key parameter. Throughout the documentation, it is assumed that you will provide this header parameter in order to access each endpoint. Below is an example of a typical header JSON object:

  "accept": "application/json",
  "cache-control": "no-cache",
  "content-type": "application/json",
  "x-api-key": "REPLACE_KEY_VALUE"

API keys are used to track requests associated with an account for quota, billing, and analytics purposes. Please review the Terms of Service agreed to during sign-up, or contact support, if you have additional questions.

Using Access

Code snippets like those below are provided for all endpoints and methods. If you find any are missing, not working, or incomplete, please submit a support request and we’ll update the docs immediately.

To provide context, consider the below examples where you would need to replace REPLACE_KEY_VALUE with your actual API key. A basic request in a shell might look something like this:

curl --request POST \
  --url https://public-api.mapanything.io/mare/matrix \
  --header 'content-type: application/json' \
  --header 'x-api-key: REPLACE_KEY_VALUE' \
  --data @/path/to/data/payload.json

Or, if you’re more comfortable reading JavaScript:

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://public-api.mapanything.io/mare/matrix",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "x-api-key": "REPLACE_KEY_VALUE"
  "processData": false,
  "data": "a properly formatted request JSON payload"
$.ajax(settings).done(function (response) {

Here is a final example in Python:

import requests
url = "https://public-api.mapanything.io/mare/matrix"
payload = "a properly formatted request JSON payload"
headers = {
    'content-type': "application/json",
    'x-api-key': "REPLACE_KEY_VALUE"
response = requests.request("POST", url, data=payload, headers=headers)

Securing Access

When you receive credentials, please take steps to secure them properly. Exposing credentials can result in unauthorized access, which can lead to billable events. To help keep your credentials secure, follow these best practices:

  • Do not embed credentials in code
  • Store credentials separately from the code base, for example using Docker Secrets or git-crypt
  • Set up account restrictions
  • Delete unused credentials
  • Regenerate credentials periodically
  • Automate detection of exposed keys using native functionality in platforms like GitHub or Gitlab, or add the functionality with tools like git-secret or git-secrets



Any tool or programming language that has HTTP communication abilities, for example cURL or Postman or Python requests, can interact with our API Platform by simply requesting the correct endpoint, for example /routing. All requests need to be made using the HTTPS protocol to ensure encryption and an extra layer of security. Additionally, most of our endpoints expect requests to be made in the standard JSON format. Our API’s support the standard HTTP methods, e.g. GET, POST, and so on.


All API’s require that the contents of request objects be encoded using UTF-8. To represent special characters in strings, use the %FF hexadecimal representation. For example, in German, the word "airports" is "Flughäfen" and converts to "Flugh%C3%A4fen." If you are unsure of the conversion, there are numerous online encoder/decoder tools and automated encoding/decoding in language specific libraries.

For example (in Python 3.0+):

from requests.utils import quote

>>> 'Flugh%C3%A4fen'

For a full-fledged URI request (in Python 3.0+):

from requests.utils import requote_uri
url = "https://api.mapanything.io/geocode/Flughäfen around Hamburg, Germany"

>>> 'https://api.mapanything.io/geocode/Flugh%C3%A4fen%20around%20Hamburg,%20Germany'



All success responses include standard HTTP statuses consistent with IETF standards. When an API request is processed successfully, a response will be returned with a JSON object as the body. The JSON object contents will be specific to the resource and are described in the detailed documentation for each resource. The API backend handles requests in one of two ways:

  • Synchronously: For smaller jobs (in terms of the number of unique locations), the request will process "quickly" (shorter than a connection timeout) and the response JSON body will include a result.

  • Asynchronously: For larger jobs, the request will not process quickly and the response JSON body will include a jobid needed to poll the endpoint and retrieve a url to download the solution. Solutions are available at this URL for 24 hours from the timestamp included in the response header.


All failure responses include standard HTTP statuses consistent with IETF standards. In the event an error occurs, the response will be a JSON with a top-level error code, error message, and other identifying information. All API errors return a JSON response with a human-readable comment describing the issue. Depending on the error returned, there may be additional objects to further describe the error.


Minor updates and bug fixes are implemented continuously and preserve existing API behavior. Major updates that alter API behavior are released to a new URL leveraging versioning, for example https://api.mapanything.io/{api-version}/routing where {api-version} might be v1, v2, v3 and so on. All changes are noted in the CHANGELOG. Changes that are considered backward compatible:

  • Changing a parameter from required to optional
  • Adding enumeration values
  • Adding new functionality

API versions are embedded in the URL to ensure that releases do not create a breaking change. For example, in the release from v1 to v2, clients on v1 will not be affected because the URL to v1 will still be valid and consistent with the v1 specifications.

When a legacy API version reaches its end-of-life and will no longer be accessible, all users will be notified 90 days in-advance to ensure that applications can be updated to a newer API version. In addition, requests to retired API versions will receive a default error response with a 30x status code and message pointing to the latest version of that API.

Units of Measure

Metric System

For units of measure, the MapAnything API Platform uses the metric system. When in doubt, assume a standard metric unit. If you encounter uncertainty, please submit a support request, and we will update the offending API to provide clarity.

  • Time: seconds
  • Distance: meters
  • Volume: arbitrary, but must be consistent across the entire request
  • Weight: arbitrary, but must be consistent across the entire request

Geographic Coordinates

The MapAnything API Platform expects geographic coordinates in units of decimal degrees using the WGS84 coordinate system. The polyline format is used to encode a sequence of locations in a single string. This is used in some endpoint responses, for example, the routes object in the response from the routing endpoint.


The MapAnything Platform expresses time in two ways:

  1. ISO 8601: this is the most self-consistent, time zone independent form of time measurement and is useful for quickly parsing and processing times across many time zones. The ISO 8601 format enables users to take advantage of modern programming libraries and modules which are time zone aware.

  2. Unix time: Unix time represents a point in time as the number of seconds that have elapsed since 00:00:00 UTC on Thursday, 1 January 1970, minus leap seconds. Parameters expressed in Unix time will always be a signed 64-bit integer. Why you may ask? So that the times will be valid until 15:30:08 UTC on Sunday, 4 December 292,277,026,596… giving you plenty of time to worry about code refactoring and technical debt.

Time zone names and offsets are specified using the Internet Assigned Numbers Authority. This adoption was made so that users can leverage modern DateTime parsing libraries such as CCTZ in C++ or datetime in Python or Date in Javascript.

Note that if a user submits a time as a string expression which includes a time zone offset, the time zone offset will be used in converting to Unix time. If no time zone is given, then the API Platform attempts to associate that particular time with a location and then the time zone of that location is used when converting to Unix time. The Platform maintains its own timezone service in order to facilitate this functionality.

To highlight why these choices have been made for the time formats, consider a timestamp in seconds. Using the handy Python pytz module, one can process time in a generalized, robust manner using only a few lines of code:

import pytz
from datetime import datetime as dt

unix_time = int("981173106")
time_zone = pytz.timezone("America/New_York")

local_time = dt.fromtimestamp(unix_time, time_zone).isoformat()
utc_time = dt.utcfromtimestamp(unix_time).isoformat()

>>> '2001-02-02T23:05:06-05:00'

>>> '2001-02-03T04:05:06'

Cross-Origin Resource Sharing

The API Platform features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.


Our documentation is built using the OpenAPI Specification and the full spec for each API is available at the top of the API’s docs page via the "Download" button. We encourage others to continue support of the OpenAPI Initiative to ensure harmonization among the universe of API’s.