Mapricot API reference

Mapricot's API is plain HTTPS. Send query parameters, or a JSON body for batches, routes, and isochrones, and get JSON back. The base URL is:

Base URL

https://api.mapricot.com

A machine-readable OpenAPI 3.1 description is at https://api.mapricot.com/openapi.json.

Authentication

Send your API key as a bearer token on every request:

Request header

Authorization: Bearer mapricot_sk_…

Create keys in the dashboard. Each key has one or more scopes, geocoding, places, routing, ip-geolocation, and tiles, and can only call endpoints in those scopes. The full key is shown once, when you create it, and a key can have an expiry date. Keys can't manage accounts, members, other keys, or billing. API keys explains server and browser keys, caps, and rotating keys.

Browsers can call the API directly from any website. A key in a web page is visible to anyone who opens the page, so use a browser key there, which works only from the origins you allow, and keep server keys on your servers.

Endpoints

Scope	Endpoint	Description
`geocoding`	`GET /geocoding/v1/search`	Find addresses and places matching text
`geocoding`	`POST /geocoding/v1/search/batch`	Run up to 100 searches in one request
`geocoding`	`GET /geocoding/v1/autocomplete`	Suggest addresses and places as someone types
`geocoding`	`GET /geocoding/v1/reverse`	Find the address nearest a coordinate, or the area around it
`places`	`GET /places/v1/nearby`	List places of a category around a coordinate
`places` or `geocoding`	`GET /places/v1/{id}`	Look up one place by its Mapricot ID
`routing`	`POST /routing/v1/route`	Find a driving, cycling, or walking route through 2 to 20 waypoints
`routing`	`POST /routing/v1/optimize`	Find a fast order to visit 2 to 20 waypoints, keeping the first and last in place, and the route through them
`routing`	`POST /routing/v1/isochrone`	Find the area reachable from a point within up to 4 travel times
`ip-geolocation`	`GET /ip-geolocation/v1/{ip}`	Approximate location of a public IP address
`tiles`	`GET /tiles/v1/styles/{style}.json`	A MapLibre style, `light`, `dark`, `bright`, `grayscale`, or `outdoors`. Free
`tiles`	`GET /tiles/v1/planet.json`	The tiles' TileJSON, for a style of your own. Free

Each path starts with its product, which is also its scope, then the product's version. Each endpoint's parameters and responses are on its docs page. Map tiles take the key in the URL, as ?key=, since MapLibre can't send headers, and are never billed. The tiles, fonts, and icons a style points to need no key.

Parameters

Unknown, repeated, or malformed parameters return 400. Coordinates are decimal degrees at any precision, such as a float as your language prints it, and are rounded to seven decimal places. focus takes a single lat,lon pair, and country takes up to 10 ISO 3166-1 alpha-2 codes, comma separated. Every geocoding and places endpoint takes an optional lang, an ISO 639-1 code such as fr, for the language of result names and labels; it defaults to en, and a region such as en-US, as browsers report it, is ignored.

Responses

Successful responses are JSON. Geocoding and places endpoints return {"results": […], "attribution": […]}, or {"result": {…}, "attribution": […]} for a single place, a route or optimized route returns {"routes": […], "attribution": […]}, and an isochrone returns a GeoJSON {"type": "FeatureCollection", "features": […], "attribution": […]}. A batch of searches returns {"responses": […]}, with each search's response, or its error, in the order of the queries. attribution names the sources of the results, and Attribution lists what each requires when your app displays them.

Every response, including errors, carries an X-Request-Id header. For a billed request, it matches that request's line in your usage export. Responses aren't cached: they're sent with Cache-Control: no-store.

Errors

Errors use the same shape on every endpoint. A search with no text returns 400:

Request

curl "https://api.mapricot.com/geocoding/v1/search?q=" \
  -H "Authorization: Bearer $MAPRICOT_KEY"

Response

{  "error": {    "code": "invalid_request",    "message": "q is empty."  },  "requestId": "01a194cd-8781-7e0e-90a3-8e0de2f8f027"}

requestId is the same ID as the X-Request-Id header.

Status	Meaning
`400`	Invalid parameters, or the request was rejected, such as a route over a mode's distance limit. The message says which parameter and what it takes
`401`	The key is missing, invalid, revoked, or expired, or its account is disabled or deleted
`403`	The key doesn't have the endpoint's scope, or it's a browser key used from an origin it doesn't allow
`404`	The place ID doesn't resolve; search again
`429`	Too many of the account's requests are in progress at once, the key's caps are used, or the account is out of credit
`502`	The service returned an invalid response
`503`	The service is unavailable or overloaded; retry later
`504`	The request didn't finish in time

Errors aren't billed.

Billing

A request uses one unit when it completes, whichever endpoint served it, and a batch one unit per completed search. The first 250,000 every 30 days are free across every API; after that, each costs $0.0001, paid as you go from prepaid credits. Searches count even with no results, and IP lookups count even with "found": false. Routes with no path, invalid requests, and errors don't count.

A retry is a new request: if the original completed, the retry counts again. See pricing for details.

Limits

Each account can have a limited number of requests in progress at once. Requests over that return 429. There's no per-minute rate limit, unless you give a key caps.
Request bodies are limited to 16 KiB, or 512 KiB for a batch of searches, which holds up to 100.
A request that takes longer than about 30 seconds returns 504.

Data releases

Each API serves one data release at a time, and data changes between releases. A place ID can stop resolving after an update; when /places/v1/{id} returns 404, search again.