API reference

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

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:

Authorization: Bearer mapricot_sk_…

Create keys in the dashboard. Each key has one or more scopes, places, routing, and ip-geolocation, 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.

Browsers can call the API directly from any website. A key in a web page is visible to anyone who opens the page, so give browser keys only the scopes they need, and keep keys with wider access on your servers.

Endpoints

Scope	Endpoint	Description
`places`	`GET /v1/search`	Find addresses and places matching text
`places`	`GET /v1/autocomplete`	Suggest addresses and places as someone types
`places`	`GET /v1/reverse`	Find the address nearest a coordinate, or the area around it
`places`	`GET /v1/nearby`	List places of a category around a coordinate
`places`	`GET /v1/places/{id}`	Look up one place by its Mapricot ID
`routing`	`POST /v1/route`	Find a driving, walking, or cycling route through 2 to 20 waypoints
`ip-geolocation`	`GET /v1/ip/{ip}`	Approximate location of a public IP address

Each endpoint's parameters and responses are on its docs page. Map tiles are served separately from tiles.mapricot.com and need no key.

Parameters

Unknown, repeated, or malformed parameters return 400. Coordinates are decimal degrees with at most 10 digits after the decimal point. focus takes a single lat,lon pair, and country takes up to 10 ISO 3166-1 alpha-2 codes, comma separated. Every 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.

Responses

Successful responses are JSON. Places endpoints return {"results": […], "attribution": […]}, or {"result": {…}, "attribution": […]} for a single place, and a route returns {"routes": […], "attribution": […]}. If your app displays results, show the credits in attribution.

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/v1/search?q=" \
  -H "Authorization: Bearer $MAPRICOT_KEY"

Response

{  "error": {    "code": "invalid_request",    "message": "The service rejected the request."  },  "request_id": "01a16b11-5b7f-74df-bc26-75876037dd14"}

Status	Meaning
`400`	Invalid parameters, or the request was rejected, such as a route over a mode's distance limit
`401`	Missing or invalid API key
`403`	The key doesn't have the endpoint's scope, or the account is inactive
`404`	The place ID doesn't resolve; search again
`429`	Too many of the account's requests are in progress at once, 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. 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.
Request bodies are limited to 16 KiB.
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 /v1/places/{id} returns 404, search again.