MapitProgramadores Beta mapit.me ↗

Versão 1.0.0

Referência da API

URL base https://api.mapit.me/v1. Cada pedido envia Authorization: Bearer com uma chave pessoal ou um token de acesso OAuth. A descrição para máquinas é o openapi.json. Os resumos e as descrições dos campos vêm dessa descrição e estão em inglês.

Respostas e erros

EstadoSignifica
200Corpo JSON como descrito abaixo, com um ETag fraco.
204Feito, sem corpo (DELETE).
304Nada mudou desde o ETag enviado em If-None-Match; sem corpo. Continua a contar para o limite.
400Um parâmetro da query não é válido; detail diz qual.
401Sem token, ou expirou ou foi revogado. WWW-Authenticate aponta para os metadados OAuth.
403Falta à chave ou à ligação o scope de que este endpoint precisa (insufficient_scope). Gerir ligações exige uma chave pessoal criada com Gerir ligações.
404Não disponível para esta conta. Um id desconhecido e o id de outro cliente respondem da mesma forma.
429Mais de 30 pedidos por minuto para a chave ou o token de acesso; aguardar os segundos indicados em Retry-After.
503Temporariamente indisponível; tentar mais tarde.

Os erros são application/problem+json com title, status e, quando é útil, detail. Os ids e os cursores são opacos: guardá-los, nunca os construir. As páginas têm 25 veículos; siga nextCursor até ser null.

Para consultar sem desperdício, guardar o último corpo e o respetivo ETag, e enviar If-None-Match com ele: 304 significa que nada mudou. fetchedAt e generatedAt ficam de fora da etiqueta, por isso um estado mantém a etiqueta até o veículo comunicar algo novo. As respostas nunca ficam em cache (Cache-Control: no-store).

Endpoints

GET/v1/me

Signed-in account.

ParâmetroEmTipoDescrição
If-None-MatchheaderstringETag of the body you already have.

Devolve Account.

GET/v1/me/connectionsrequer uma chave pessoal com Gerir ligações

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âmetroEmTipoDescrição
If-None-MatchheaderstringETag of the body you already have.

Devolve um objeto com connections (Connection[]).

DELETE/v1/me/connections/{connectionId}requer uma chave pessoal com Gerir ligações

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âmetroEmTipoDescrição
connectionId (obrigatório)pathstringConnection id from /v1/me/connections.

GET/v1/summary

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

ParâmetroEmTipoDescrição
vehicleCursorquerystringNext page of vehicles.
transferCursorquerystringNext page of incoming transfers.
If-None-MatchheaderstringETag of the body you already have.

Devolve um objeto.

GET/v1/vehicles

Vehicles the Mapit app shows, 25 per page.

ParâmetroEmTipoDescrição
cursorquerystringnextCursor from the previous page.
If-None-MatchheaderstringETag of the body you already have.

Devolve um objeto com vehicles (Vehicle[]), nextCursor (string ou null).

GET/v1/vehicles/{vehicleId}

One vehicle.

ParâmetroEmTipoDescrição
vehicleId (obrigatório)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
If-None-MatchheaderstringETag of the body you already have.

Devolve Vehicle.

GET/v1/vehicles/{vehicleId}/subscription

Stored subscription status.

ParâmetroEmTipoDescrição
vehicleId (obrigatório)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
If-None-MatchheaderstringETag of the body you already have.

Devolve um objeto com subscription (Subscription ou null).

GET/v1/statusrequer 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âmetroEmTipoDescrição
cursorquerystringnextCursor from the previous page.
If-None-MatchheaderstringETag of the body you already have.

Devolve um objeto com vehicles (Status[]), nextCursor (string ou null).

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

Last reported status of one vehicle.

ParâmetroEmTipoDescrição
vehicleId (obrigatório)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
If-None-MatchheaderstringETag of the body you already have.

Devolve Status.

GET/v1/vehicles/{vehicleId}/routesrequer 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âmetroEmTipoDescrição
vehicleId (obrigatório)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.

Devolve um objeto com routes (Route[]), nextCursor (string ou null), filter (object).

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

One route, optionally with its GeoJSON line.

ParâmetroEmTipoDescrição
vehicleId (obrigatório)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
routeId (obrigatório)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.

Devolve um objeto com route (Route).

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

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

ParâmetroEmTipoDescrição
vehicleId (obrigatório)pathstringVehicle id from /v1/vehicles. Ids are opaque and differ per account.
from (obrigatório)querystring (date)First local day.
to (obrigatório)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.

Devolve um objeto.

Objetos

Account

CampoTipoNotas
namestring
emailstring

Vehicle

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

Subscription

CampoTipoNotas
statusstring
periodEndstring ou null (date-time)
cancelAtEndboolean

Status

CampoTipoNotas
vehicleIdstring
stateobject ou null
reasonstring ou 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 ou null (date-time)
distanceMetersnumber ou null
durationSecondsnumber ou null
avgSpeedKmhnumber ou null
maxSpeedKmhnumber ou null
startTimezonestring ou null