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
| Estado | Significa |
|---|---|
200 | Corpo JSON como descrito abaixo, com um ETag fraco. |
204 | Feito, sem corpo (DELETE). |
304 | Nada mudou desde o ETag enviado em If-None-Match; sem corpo. Continua a contar para o limite. |
400 | Um parâmetro da query não é válido; detail diz qual. |
401 | Sem token, ou expirou ou foi revogado. WWW-Authenticate aponta para os metadados OAuth. |
403 | Falta à 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. |
404 | Não disponível para esta conta. Um id desconhecido e o id de outro cliente respondem da mesma forma. |
429 | Mais de 30 pedidos por minuto para a chave ou o token de acesso; aguardar os segundos indicados em Retry-After. |
503 | Temporariamente 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âmetro | Em | Tipo | Descrição |
|---|---|---|---|
If-None-Match | header | string | ETag 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âmetro | Em | Tipo | Descrição |
|---|---|---|---|
If-None-Match | header | string | ETag 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âmetro | Em | Tipo | Descrição |
|---|---|---|---|
connectionId (obrigatório) | path | string | Connection id from /v1/me/connections. |
GET/v1/summary
Account, vehicles with device and subscription, and incoming vehicle transfers.
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
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. |
Devolve um objeto.
GET/v1/vehicles
Vehicles the Mapit app shows, 25 per page.
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
cursor | query | string | nextCursor from the previous page. |
If-None-Match | header | string | ETag of the body you already have. |
Devolve um objeto com vehicles (Vehicle[]), nextCursor (string ou null).
GET/v1/vehicles/{vehicleId}
One vehicle.
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
vehicleId (obrigatório) | 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. |
Devolve Vehicle.
GET/v1/vehicles/{vehicleId}/subscription
Stored subscription status.
| Parâmetro | Em | Tipo | Descrição |
|---|---|---|---|
vehicleId (obrigatório) | 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. |
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âmetro | Em | Tipo | Descrição |
|---|---|---|---|
cursor | query | string | nextCursor from the previous page. |
If-None-Match | header | string | ETag 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âmetro | Em | Tipo | Descrição |
|---|---|---|---|
vehicleId (obrigatório) | 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. |
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âmetro | Em | Tipo | Descrição |
|---|---|---|---|
vehicleId (obrigatório) | 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. |
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âmetro | Em | Tipo | Descrição |
|---|---|---|---|
vehicleId (obrigatório) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
routeId (obrigatório) | 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. |
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âmetro | Em | Tipo | Descrição |
|---|---|---|---|
vehicleId (obrigatório) | path | string | Vehicle id from /v1/vehicles. Ids are opaque and differ per account. |
from (obrigatório) | query | string (date) | First local day. |
to (obrigatório) | 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. |
Devolve um 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 ou null (date-time) | |
cancelAtEnd | boolean |
Status
| Campo | Tipo | Notas |
|---|---|---|
vehicleId | string | |
state | object ou null | |
reason | string ou 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 ou null (date-time) | |
distanceMeters | number ou null | |
durationSeconds | number ou null | |
avgSpeedKmh | number ou null | |
maxSpeedKmh | number ou null | |
startTimezone | string ou null |
