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
| Status | Means |
|---|---|
200 | JSON body as described below, with a weak ETag. |
204 | Done, no body (DELETE). |
304 | Nothing changed since the ETag you sent in If-None-Match; no body. Still counts towards the limit. |
400 | A query parameter is wrong; detail says which. |
401 | No token, or it expired or was revoked. WWW-Authenticate points at the OAuth metadata. |
403 | The key or connection lacks the scope this endpoint needs (insufficient_scope). Managing connections needs a personal key created with Manage connections. |
404 | Not available for this account. An unknown id and another customer's id answer the same. |
429 | Over 30 requests a minute for the key or access token; wait Retry-After seconds. |
503 | Temporarily 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.
| Parameter | In | Type | Description |
|---|---|---|---|
If-None-Match | header | string | ETag 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.
| Parameter | In | Type | Description |
|---|---|---|---|
If-None-Match | header | string | ETag 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.
| Parameter | In | Type | Description |
|---|---|---|---|
connectionId (required) | path | string | Connection id from /v1/me/connections. |
GET/v1/summary
Account, vehicles with device and subscription, and incoming vehicle transfers.
| Parameter | In | Type | Description |
|---|---|---|---|
vehicleCursor | query | string | Next page of vehicles. |
transferCursor | query | string | Next page of incoming transfers. |
If-None-Match | header | string | ETag of the body you already have. |
Returns an object.
GET/v1/vehicles
Vehicles the Mapit app shows, 25 per page.
| Parameter | In | Type | Description |
|---|---|---|---|
cursor | query | string | nextCursor from the previous page. |
If-None-Match | header | string | ETag of the body you already have. |
Returns an object with vehicles (Vehicle[]), nextCursor (string or null).
GET/v1/vehicles/{vehicleId}
One vehicle.
| Parameter | In | Type | Description |
|---|---|---|---|
vehicleId (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
If-None-Match | header | string | ETag of the body you already have. |
Returns Vehicle.
GET/v1/vehicles/{vehicleId}/subscription
Stored subscription status.
| Parameter | In | Type | Description |
|---|---|---|---|
vehicleId (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
If-None-Match | header | string | ETag 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.
| Parameter | In | Type | Description |
|---|---|---|---|
cursor | query | string | nextCursor from the previous page. |
If-None-Match | header | string | ETag 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.
| Parameter | In | Type | Description |
|---|---|---|---|
vehicleId (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
If-None-Match | header | string | ETag 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.
| Parameter | In | Type | Description |
|---|---|---|---|
vehicleId (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
day | query | string (date) | Local day, YYYY-MM-DD. Not with from/to. |
from | query | string (date-time) | Inclusive start, with offset. |
to | query | string (date-time) | Exclusive end, with offset; at most 93 days. |
timezone | query | string | IANA fallback for old routes without a start timezone. |
limit | query | integer | Page size. |
cursor | query | string | nextCursor from the previous page. |
If-None-Match | header | string | ETag 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.
| Parameter | In | Type | Description |
|---|---|---|---|
vehicleId (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
routeId (required) | path | string | Route id from the routes list. |
geometry | query | boolean | Include GeoJSON; omitted when larger than 40 KB. |
simplify | query | boolean | GeoJSON thinned to fit 40 KB; implies geometry. |
If-None-Match | header | string | ETag 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.
| Parameter | In | Type | Description |
|---|---|---|---|
vehicleId (required) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
from (required) | query | string (date) | First local day. |
to (required) | query | string (date) | Last local day, inclusive; at most 90 days. |
timezone | query | string | IANA timezone; defaults to the account's. |
If-None-Match | header | string | ETag of the body you already have. |
Returns an object.
Objects
Account
| Field | Type | Notes |
|---|---|---|
name | string | |
email | string |
Vehicle
| Field | Type | Notes |
|---|---|---|
id | string | |
name | string | |
registrationNumber | string | |
model | string | |
km | number | Stored mileage, not live |
products | string[] | |
cancelled | boolean | |
blockedByTransfer | boolean |
Subscription
| Field | Type | Notes |
|---|---|---|
status | string | |
periodEnd | string or null (date-time) | |
cancelAtEnd | boolean |
Status
| Field | Type | Notes |
|---|---|---|
vehicleId | string | |
state | object or null | |
reason | string or null | Why there is no state: blocked_by_transfer, subscription_cancelled or no_linked_device |
voltageNote | string | |
source | string | |
fetchedAt | string (date-time) |
Connection
| Field | Type | Notes |
|---|---|---|
id | string | |
kind | string | |
name | string | The key's name, or the name the app registered with (unverified unless builtIn) |
builtIn | boolean | A client built into Mapit, such as Home Assistant |
api | string | |
scopes | string[] | |
createdAt | string (date-time) | |
expiresAt | string (date-time) | For apps, it moves on each token refresh |
current | boolean | The key making this request |
Route
| Field | Type | Notes |
|---|---|---|
id | string | |
vehicleId | string | |
startedAt | string (date-time) | |
endedAt | string or null (date-time) | |
distanceMeters | number or null | |
durationSeconds | number or null | |
avgSpeedKmh | number or null | |
maxSpeedKmh | number or null | |
startTimezone | string or null |
