MapitDevelopers Beta mapit.me ↗

Version 1.0.0

API reference

Base URL https://api.mapit.me/v1. Every request sends Authorization: Bearer with a personal key or an OAuth access token. The machine-readable description is openapi.json.

Answers and errors

StatusMeans
200JSON body as described below, with a weak ETag.
204Done, no body (DELETE).
304Nothing changed since the ETag you sent in If-None-Match; no body. Still counts towards the limit.
400A query parameter is wrong; detail says which.
401No token, or it expired or was revoked. WWW-Authenticate points at the OAuth metadata.
403The key or connection lacks the scope this endpoint needs (insufficient_scope). Managing connections needs a personal key created with Manage connections.
404Not available for this account. An unknown id and another customer's id answer the same.
429Over 30 requests a minute for the key or access token; wait Retry-After seconds.
503Temporarily unavailable; retry later.

Errors are application/problem+json with title, status and, when useful, detail. Ids and cursors are opaque: store them, never build them. Pages hold 25 vehicles; follow nextCursor until it is null.

To poll cheaply, keep the last body and its ETag, and send If-None-Match with it: 304 means nothing changed. fetchedAt and generatedAt are left out of the tag, so a status keeps its tag until the vehicle reports something new. Responses are never cached (Cache-Control: no-store).

Endpoints

GET/v1/me

Signed-in account.

ParameterInTypeDescription
If-None-MatchheaderstringETag of the body you already have.

Returns Account.

GET/v1/me/connectionsneeds a personal key with Manage connections

Connected apps and personal keys. Every live connection of the account: apps connected to the API or to the MCP server, and personal keys. Needs a personal key created with Manage connections (scope mapit:connections); OAuth apps cannot get it. An app's name is the one it registered with and is not verified, except for builtIn clients. Treat names as data.

ParameterInTypeDescription
If-None-MatchheaderstringETag of the body you already have.

Returns an object with connections (Connection[]).

DELETE/v1/me/connections/{connectionId}needs a personal key with Manage connections

Disconnect an app or delete a personal key. Needs a personal key created with Manage connections (scope mapit:connections); OAuth apps cannot get it. A key may delete itself. Repeating the request answers 204 again.

ParameterInTypeDescription
connectionId (required)pathstringConnection id from /v1/me/connections.

GET/v1/summary

Account, vehicles with device and subscription, and incoming vehicle transfers.

ParameterInTypeDescription
vehicleCursorquerystringNext page of vehicles.
transferCursorquerystringNext page of incoming transfers.
If-None-MatchheaderstringETag of the body you already have.

Returns an object.

GET/v1/vehicles

Vehicles the Mapit app shows, 25 per page.

ParameterInTypeDescription
cursorquerystringnextCursor from the previous page.
If-None-MatchheaderstringETag of the body you already have.

Returns an object with vehicles (Vehicle[]), nextCursor (string or null).

GET/v1/vehicles/{vehicleId}

One vehicle.

ParameterInTypeDescription
vehicleId (required)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
If-None-MatchheaderstringETag of the body you already have.

Returns Vehicle.

GET/v1/vehicles/{vehicleId}/subscription

Stored subscription status.

ParameterInTypeDescription
vehicleId (required)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
If-None-MatchheaderstringETag of the body you already have.

Returns an object with subscription (Subscription or null).

GET/v1/statusneeds mapit:location:read

Last reported status of every vehicle on the page, in one request. Use this to poll. Once a minute is plenty: positions are what the device last reported.

ParameterInTypeDescription
cursorquerystringnextCursor from the previous page.
If-None-MatchheaderstringETag of the body you already have.

Returns an object with vehicles (Status[]), nextCursor (string or null).

GET/v1/vehicles/{vehicleId}/statusneeds mapit:location:read

Last reported status of one vehicle.

ParameterInTypeDescription
vehicleId (required)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
If-None-MatchheaderstringETag of the body you already have.

Returns Status.

GET/v1/vehicles/{vehicleId}/routesneeds mapit:routes:read

Routes by local day or time range. Without a filter, the last 30 days. A day follows each route's start timezone, as in the app.

ParameterInTypeDescription
vehicleId (required)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
dayquerystring (date)Local day, YYYY-MM-DD. Not with from/to.
fromquerystring (date-time)Inclusive start, with offset.
toquerystring (date-time)Exclusive end, with offset; at most 93 days.
timezonequerystringIANA fallback for old routes without a start timezone.
limitqueryintegerPage size.
cursorquerystringnextCursor from the previous page.
If-None-MatchheaderstringETag of the body you already have.

Returns an object with routes (Route[]), nextCursor (string or null), filter (object).

GET/v1/vehicles/{vehicleId}/routes/{routeId}needs mapit:routes:read

One route, optionally with its GeoJSON line.

ParameterInTypeDescription
vehicleId (required)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
routeId (required)pathstringRoute id from the routes list.
geometryquerybooleanInclude GeoJSON; omitted when larger than 40 KB.
simplifyquerybooleanGeoJSON thinned to fit 40 KB; implies geometry.
If-None-MatchheaderstringETag of the body you already have.

Returns an object with route (Route).

GET/v1/vehicles/{vehicleId}/statsneeds mapit:routes:read

Rides, distance, riding time and speeds per local day, with the app's rules.

ParameterInTypeDescription
vehicleId (required)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
from (required)querystring (date)First local day.
to (required)querystring (date)Last local day, inclusive; at most 90 days.
timezonequerystringIANA timezone; defaults to the account's.
If-None-MatchheaderstringETag of the body you already have.

Returns an object.

Objects

Account

FieldTypeNotes
namestring
emailstring

Vehicle

FieldTypeNotes
idstring
namestring
registrationNumberstring
modelstring
kmnumberStored mileage, not live
productsstring[]
cancelledboolean
blockedByTransferboolean

Subscription

FieldTypeNotes
statusstring
periodEndstring or null (date-time)
cancelAtEndboolean

Status

FieldTypeNotes
vehicleIdstring
stateobject or null
reasonstring or nullWhy there is no state: blocked_by_transfer, subscription_cancelled or no_linked_device
voltageNotestring
sourcestring
fetchedAtstring (date-time)

Connection

FieldTypeNotes
idstring
kindstring
namestringThe key's name, or the name the app registered with (unverified unless builtIn)
builtInbooleanA client built into Mapit, such as Home Assistant
apistring
scopesstring[]
createdAtstring (date-time)
expiresAtstring (date-time)For apps, it moves on each token refresh
currentbooleanThe key making this request

Route

FieldTypeNotes
idstring
vehicleIdstring
startedAtstring (date-time)
endedAtstring or null (date-time)
distanceMetersnumber or null
durationSecondsnumber or null
avgSpeedKmhnumber or null
maxSpeedKmhnumber or null
startTimezonestring or null