MapitDesarrolladores Beta mapit.me ↗

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

EstadoSignifica
200Cuerpo JSON como se describe abajo, con un ETag débil.
204Hecho, sin cuerpo (DELETE).
304Nada ha cambiado desde el ETag que enviaste en If-None-Match; sin cuerpo. Sigue contando para el límite.
400Un parámetro de la consulta no es válido; detail dice cuál.
401No hay token, o caducó o se revocó. WWW-Authenticate apunta a los metadatos de OAuth.
403A 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.
404No disponible para esta cuenta. Un id desconocido y el id de otro cliente responden igual.
429Más de 30 peticiones por minuto para la clave o el token de acceso; espera los segundos que indica Retry-After.
503No 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ámetroEnTipoDescripción
If-None-MatchheaderstringETag 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ámetroEnTipoDescripción
If-None-MatchheaderstringETag 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ámetroEnTipoDescripción
connectionId (obligatorio)pathstringConnection id from /v1/me/connections.

GET/v1/summary

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

ParámetroEnTipoDescripción
vehicleCursorquerystringNext page of vehicles.
transferCursorquerystringNext page of incoming transfers.
If-None-MatchheaderstringETag of the body you already have.

Devuelve un objeto.

GET/v1/vehicles

Vehicles the Mapit app shows, 25 per page.

ParámetroEnTipoDescripción
cursorquerystringnextCursor from the previous page.
If-None-MatchheaderstringETag of the body you already have.

Devuelve un objeto con vehicles (Vehicle[]), nextCursor (string o null).

GET/v1/vehicles/{vehicleId}

One vehicle.

ParámetroEnTipoDescripción
vehicleId (obligatorio)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
If-None-MatchheaderstringETag of the body you already have.

Devuelve Vehicle.

GET/v1/vehicles/{vehicleId}/subscription

Stored subscription status.

ParámetroEnTipoDescripción
vehicleId (obligatorio)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
If-None-MatchheaderstringETag 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ámetroEnTipoDescripción
cursorquerystringnextCursor from the previous page.
If-None-MatchheaderstringETag 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ámetroEnTipoDescripción
vehicleId (obligatorio)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
If-None-MatchheaderstringETag 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ámetroEnTipoDescripción
vehicleId (obligatorio)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.

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ámetroEnTipoDescripción
vehicleId (obligatorio)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
routeId (obligatorio)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.

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ámetroEnTipoDescripción
vehicleId (obligatorio)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
from (obligatorio)querystring (date)First local day.
to (obligatorio)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.

Devuelve un objeto.

Objetos

Account

CampoTipoNotas
namestring
emailstring

Vehicle

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

Subscription

CampoTipoNotas
statusstring
periodEndstring o null (date-time)
cancelAtEndboolean

Status

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

Connection

CampoTipoNotas
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

CampoTipoNotas
idstring
vehicleIdstring
startedAtstring (date-time)
endedAtstring o null (date-time)
distanceMetersnumber o null
durationSecondsnumber o null
avgSpeedKmhnumber o null
maxSpeedKmhnumber o null
startTimezonestring o null