Overview

Authentication

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 before having access to MapAnything API’s. Your API key is provided via the request header using the x-api-key parameter. Throughout the documentation, we assume this header is provided. 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 simple 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

Alternatively, 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) {
  console.log(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)
print(response.text)

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

Requests

Methods

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 merely 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.

Encoding

All API’s require 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
quote('Flughäfen')

>>> '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"
requote_uri(url)

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

Responses

Success

All success responses include standard HTTP statuses consistent with IETF standards. The API returns a JSON object when a request is successful. The JSON object contents are specific to the resource and 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 processes "quickly" (shorter than a connection timeout) and the response JSON body includes a result.
  • Asynchronously: For larger jobs, the request does not process quickly, and the response JSON body includes 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.

Failure

All failure responses include standard HTTP statuses consistent with IETF standards. In the event an error occurs, the response is 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 describe the error further. Note that if a client does not receive a response for a request within 29 seconds, the API returns an HTTP status code of 504 indicating a Gateway Timeout Error.

Versioning

Minor updates and bug fixes are implemented continuously and preserve existing API behavior. Significant 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. The CHANGELOG tracks all changes made to the APIs. 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 are not affected because the URL to v1 is still 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 are notified 90 days in-advance to ensure that applications update to a newer API version. Also, requests to retired API versions 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 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. Polylines appear in some endpoint responses, for example, the routes object in the response from the routing endpoint.

Time

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 are signed 64-bit integers. Why may you ask? So that the times are 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 ensures 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 is 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 API Platform maintains a private timezone service to facilitate this functionality.

To highlight the reasoning for the time format choices, 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()

print(local_time)
>>> '2001-02-02T23:05:06-05:00'

print(utc_time)
>>> '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 wholly public and accessible to everyone, including any code on any site.

Documentation

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.