Versión 1.0.0
Referencia de la API
URL base https://api.mapit.me/v1. Cada petición envía Authorization: Bearer con una clave personal o un token de acceso de OAuth. La descripción para máquinas es openapi.json. Los resúmenes y las descripciones de campos vienen de esa descripción y están en inglés.
Respuestas y errores
| Estado | Significa |
|---|---|
200 | Cuerpo JSON como se describe abajo, con un ETag débil. |
204 | Hecho, sin cuerpo (DELETE). |
304 | Nada ha cambiado desde el ETag que enviaste en If-None-Match; sin cuerpo. Sigue contando para el límite. |
400 | Un parámetro de la consulta no es válido; detail dice cuál. |
401 | No hay token, o caducó o se revocó. WWW-Authenticate apunta a los metadatos de OAuth. |
403 | A la clave o la conexión le falta el scope que necesita este endpoint (insufficient_scope). Gestionar conexiones necesita una clave personal creada con Gestionar conexiones. |
404 | No disponible para esta cuenta. Un id desconocido y el id de otro cliente responden igual. |
429 | Más de 30 peticiones por minuto para la clave o el token de acceso; espera los segundos que indica Retry-After. |
503 | No disponible temporalmente; vuelve a intentarlo más tarde. |
Los errores son application/problem+json con title, status y, cuando sirve de algo, detail. Los ids y los cursores son opacos: guárdalos, nunca los construyas. Las páginas tienen 25 vehículos; sigue nextCursor hasta que sea null.
Para consultar sin gastar, guarda el último cuerpo y su ETag, y envía If-None-Match con él: 304 significa que nada ha cambiado. fetchedAt y generatedAt no cuentan para la etiqueta, así que un estado conserva su etiqueta hasta que el vehículo informa algo nuevo. Las respuestas nunca se guardan en caché (Cache-Control: no-store).
Endpoints
GET/v1/me
Signed-in account.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
If-None-Match | header | string | ETag of the body you already have. |
Devuelve Account.
GET/v1/me/connectionsnecesita una clave personal con Gestionar conexiones
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.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
If-None-Match | header | string | ETag of the body you already have. |
Devuelve un objeto con connections (Connection[]).
DELETE/v1/me/connections/{connectionId}necesita una clave personal con Gestionar conexiones
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.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
connectionId (obligatorio) | path | string | Connection id from /v1/me/connections. |
GET/v1/summary
Account, vehicles with device and subscription, and incoming vehicle transfers.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
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. |
Devuelve un objeto.
GET/v1/vehicles
Vehicles the Mapit app shows, 25 per page.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
cursor | query | string | nextCursor from the previous page. |
If-None-Match | header | string | ETag of the body you already have. |
Devuelve un objeto con vehicles (Vehicle[]), nextCursor (string o null).
GET/v1/vehicles/{vehicleId}
One vehicle.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
vehicleId (obligatorio) | 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. |
Devuelve Vehicle.
GET/v1/vehicles/{vehicleId}/subscription
Stored subscription status.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
vehicleId (obligatorio) | 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. |
Devuelve un objeto con subscription (Subscription o null).
GET/v1/statusnecesita 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.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
cursor | query | string | nextCursor from the previous page. |
If-None-Match | header | string | ETag of the body you already have. |
Devuelve un objeto con vehicles (Status[]), nextCursor (string o null).
GET/v1/vehicles/{vehicleId}/statusnecesita mapit:location:read
Last reported status of one vehicle.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
vehicleId (obligatorio) | 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. |
Devuelve Status.
GET/v1/vehicles/{vehicleId}/routesnecesita 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.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
vehicleId (obligatorio) | 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. |
Devuelve un objeto con routes (Route[]), nextCursor (string o null), filter (object).
GET/v1/vehicles/{vehicleId}/routes/{routeId}necesita mapit:routes:read
One route, optionally with its GeoJSON line.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
vehicleId (obligatorio) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
routeId (obligatorio) | 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. |
Devuelve un objeto con route (Route).
GET/v1/vehicles/{vehicleId}/statsnecesita mapit:routes:read
Rides, distance, riding time and speeds per local day, with the app's rules.
| Parámetro | En | Tipo | Descripción |
|---|---|---|---|
vehicleId (obligatorio) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
from (obligatorio) | query | string (date) | First local day. |
to (obligatorio) | 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. |
Devuelve un objeto.
Objetos
Account
| Campo | Tipo | Notas |
|---|---|---|
name | string | |
email | string |
Vehicle
| Campo | Tipo | Notas |
|---|---|---|
id | string | |
name | string | |
registrationNumber | string | |
model | string | |
km | number | Stored mileage, not live |
products | string[] | |
cancelled | boolean | |
blockedByTransfer | boolean |
Subscription
| Campo | Tipo | Notas |
|---|---|---|
status | string | |
periodEnd | string o null (date-time) | |
cancelAtEnd | boolean |
Status
| Campo | Tipo | Notas |
|---|---|---|
vehicleId | string | |
state | object o null | |
reason | string o null | Why there is no state: blocked_by_transfer, subscription_cancelled or no_linked_device |
voltageNote | string | |
source | string | |
fetchedAt | string (date-time) |
Connection
| Campo | Tipo | Notas |
|---|---|---|
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
| Campo | Tipo | Notas |
|---|---|---|
id | string | |
vehicleId | string | |
startedAt | string (date-time) | |
endedAt | string o null (date-time) | |
distanceMeters | number o null | |
durationSeconds | number o null | |
avgSpeedKmh | number o null | |
maxSpeedKmh | number o null | |
startTimezone | string o null |
