# Mapit for developers: all the docs > The Mapit API lets a Mapit customer read their own account, vehicles, last reported positions and routes from their own code, Home Assistant or an AI assistant (the My Mapit connector). It is a beta, read-only apart from disconnecting apps and keys, and for personal, non-commercial use. Resources are at https://api.mapit.me/v1, sign-in, keys and OAuth at https://login.mapit.me, and the MCP server for assistants at https://api.mapit.me/mcp. --- Source: https://developers.mapit.me/ # Your Mapit data, in your own tools Read your account, your vehicles, where they last reported and the routes you rode: the same things the Mapit app shows, from a script, Home Assistant or an app you build. Without sharing your Mapit password. > **Beta, free for now.** The Mapit API is a beta: it may change or stop, it comes with no uptime promise, and Mapit does not charge for it today. Do not rely on it for emergencies or to recover a stolen bike: use the Mapit app. [Read the beta terms](https://developers.mapit.me/terms.md). - [Personal keys](https://developers.mapit.me/keys.md): For your own scripts. Create a key, paste it, done. - [OAuth](https://developers.mapit.me/oauth.md): For apps that connect other Mapit customers, with their consent. - [Home Assistant](https://developers.mapit.me/home-assistant.md): Your bike as a device tracker and sensors. - [Use with AI](https://developers.mapit.me/ai.md): Connect an assistant to your account, or point a coding agent at these docs. - [API reference](https://developers.mapit.me/reference.md): Every endpoint, parameter and field. ## Try it With a [personal key](https://developers.mapit.me/keys.md) that can see locations: ``` curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/status ``` The answer has one entry per vehicle, with its last reported position, battery and when it last reported. ## What to know first - **Read-only.** The API cannot change your account, vehicles or settings. The one exception: a personal key with the “Manage connections” option can disconnect your apps and keys. - **Your data only.** A key or connection sees one customer's vehicles, as the Mapit app shows them. - **Location and routes are opt-in.** They need their own permission, given when the key or connection is created. - **Last reported, not live.** Positions are what the tracker last sent; every answer says when. - **30 requests a minute** per key or access token. Polling `/v1/status` once a minute is plenty. See [Limits](https://developers.mapit.me/limits.md). - **Stable, as far as a beta can be.** We aim for version 1 to only gain fields. Anything that would break your code gets `/v2`. See [Versions](https://developers.mapit.me/versions.md). ## AI assistants Claude, ChatGPT and other assistants that support MCP connect through `https://api.mapit.me/mcp`: add it as a connector and sign in with your Mapit account. [Use with AI](https://developers.mapit.me/ai.md) has the steps, and what a coding agent needs to read these docs. --- Source: https://developers.mapit.me/keys # Personal keys A personal key lets your own code read your Mapit account. It is read-only, unless you also let it manage your connections, and belongs to you: you can delete it at any time. > **Beta, free for now.** Personal keys are part of the Mapit API beta: they may change, and there is no uptime promise. See the [beta terms](https://developers.mapit.me/terms.md). ## Create a key 1. Go to [login.mapit.me/connections](https://login.mapit.me/connections) and sign in with your Mapit email and password. 2. Under **Personal keys**, give the key a name you will recognise, such as “Garage script”. 3. Tick location, route history and Manage connections only if your code needs them. 4. Enter your password again and create the key. A key keeps working even if you later change your password, so Mapit asks for it once more. 5. Copy the key. It starts with `mapit_` and is shown only once. > Treat the key like a password: keep it out of code you share and out of screenshots. If it leaks, delete it on the same page and create another. ## Use it Send it as a bearer token: ``` export MAPIT_KEY=mapit_... curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/vehicles curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/status ``` In Python: ``` import os, requests r = requests.get("https://api.mapit.me/v1/status", headers={"Authorization": f"Bearer {os.environ['MAPIT_KEY']}"}, timeout=20) r.raise_for_status() for v in r.json()["vehicles"]: s = v["state"] or {} print(v["vehicleId"], s.get("latitude"), s.get("longitude"), s.get("lastLocationAt")) ``` ## What a key can do | Permission | Always | When ticked | | --- | --- | --- | | Account, vehicles, subscription | Yes | | | Last reported location and device status | | Location | | Route history and ride statistics | | Route history | | List and disconnect your connected apps and keys | | Manage connections | A request outside the key's permissions answers `403`. To change them, create a new key. ## Poll without downloading the same data Every answer carries an `ETag`. Send it back in `If-None-Match`; `304` with no body means nothing changed. It still counts towards the 30 requests a minute. ``` # The first answer carries the tag curl -sD- -o status.json -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/status # Send it back: 304 and no body until a vehicle reports something new curl -sD- -o status.json -H "Authorization: Bearer $MAPIT_KEY" -H 'If-None-Match: W/"..."' https://api.mapit.me/v1/status ``` ## Manage connections A key created with **Manage connections** can list every app connected to your account (Home Assistant, Claude, ChatGPT…) and every key, and disconnect any of them. Only personal keys can have this; no app can ask for it. The connections page marks such keys “can manage connections”. ``` curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/me/connections curl -X DELETE -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/me/connections/con_... ``` > A key with this permission can disconnect your apps. Give it only to code you trust, and if connections keep disappearing, delete the keys marked “can manage connections”. An app's `name` is the one it gave itself unless `builtIn` is true. ## Limits See [Limits](https://developers.mapit.me/limits.md) for the current numbers. Today: - A key lasts one year. The [connections page](https://login.mapit.me/connections) shows when each one expires. - Up to 10 keys per account. - 30 requests a minute per key; over that the API answers `429` with `Retry-After` in seconds. --- Source: https://developers.mapit.me/oauth # OAuth Use OAuth when your app acts for Mapit customers other than you. Each customer signs in on Mapit's own page, sees what your app asks for and decides. Your app never sees their password. > **Beta, free for now.** OAuth for apps is part of the Mapit API beta: details may change, and there is no uptime promise. See the [beta terms](https://developers.mapit.me/terms.md). ## The basics - OAuth 2.1 authorization code flow with PKCE (`S256`). Public clients only: no client secret. - Every authorization and token request carries `resource=https://api.mapit.me/v1`. A token is valid only for the resource it was issued for. - Two hosts: the API at `https://api.mapit.me`, and sign-in and the OAuth endpoints at `https://login.mapit.me`. - Discovery: [`https://api.mapit.me/.well-known/oauth-protected-resource/v1`](https://api.mapit.me/.well-known/oauth-protected-resource/v1) names the authorization server; its metadata is at [`https://login.mapit.me/.well-known/oauth-authorization-server`](https://login.mapit.me/.well-known/oauth-authorization-server). ## Scopes | Scope | Gives | | --- | --- | | `mapit:read` | Account, vehicles and subscription. Required. | | `mapit:location:read` | Last reported location and device status. | | `mapit:routes:read` | Route history and ride statistics. | | `offline_access` | A refresh token, so your app stays connected. | Location and routes are checkboxes on the consent page, and the customer may leave them unticked. Read the `scope` in the token response to know what you got. ## 1. Register your app Dynamic client registration accepts native apps that listen on a loopback address (RFC 8252): ``` curl -X POST https://login.mapit.me/oauth/register \ -H "Content-Type: application/json" \ -d '{"client_name": "My app", "redirect_uris": ["http://127.0.0.1:8765/callback"]}' ``` The port may change between runs; the path must be `/callback`. For a web app with an HTTPS redirect, ask us to add it: redirects are an allowlist, so nobody can pose as your app. ## 2. Send the customer to sign in ``` https://login.mapit.me/oauth/authorize ?response_type=code &client_id=CLIENT_ID &redirect_uri=http://127.0.0.1:8765/callback &code_challenge=BASE64URL(SHA256(verifier)) &code_challenge_method=S256 &resource=https://api.mapit.me/v1 &scope=mapit:read mapit:location:read offline_access &state=RANDOM ``` Mapit redirects back with `code`, your `state` and `iss=https://login.mapit.me`, or with `error=access_denied` if the customer cancels. ## 3. Exchange the code ``` curl -X POST https://login.mapit.me/oauth/token \ -d grant_type=authorization_code -d code=CODE -d client_id=CLIENT_ID \ -d redirect_uri=http://127.0.0.1:8765/callback -d code_verifier=VERIFIER \ -d resource=https://api.mapit.me/v1 ``` The code works once, for one minute. The answer has `access_token` (15 minutes), `refresh_token` and `scope`. ## 4. Refresh ``` curl -X POST https://login.mapit.me/oauth/token \ -d grant_type=refresh_token -d refresh_token=REFRESH_TOKEN \ -d client_id=CLIENT_ID -d resource=https://api.mapit.me/v1 ``` Each refresh token works once and comes back with a new one. Store the new one before using the access token. Sending a refresh token a second time ends the connection, because it means the token was copied: refresh from one place at a time. ## How long a connection lasts - 30 days from the last refresh. An app that refreshes keeps it alive. - One year from sign-in at most; then the customer signs in again. - The customer can disconnect your app at any time on [login.mapit.me/connections](https://login.mapit.me/connections). Your next request answers `401`. --- Source: https://developers.mapit.me/ai # Use Mapit with AI Two ways to use Mapit with AI: ask an assistant about your own bike, or have a coding agent write the code that reads it. > **Beta, free for now.** My Mapit and the service behind it are a beta: they may change or stop, they come with no uptime promise, and Mapit does not charge for them today. Do not rely on them for emergencies or to recover a stolen bike: use the Mapit app. See the [beta terms](https://developers.mapit.me/terms.md). ## Ask an assistant about your bike **My Mapit** (Mi Mapit in Spanish) connects an AI assistant to your own Mapit account. Ask “Where is my bike?”, “What rides did I do yesterday?” or “When does my subscription end?”. You sign in with your Mapit account on Mapit's page, and you choose what the assistant may see. It never gets your password. ### Plugin or connector My Mapit comes two ways. The **plugin** bundles the My Mapit connector with two skills. The marketplace `mapit-iot/ai-plugin` (a GitHub repository) is added in Claude Code and Codex below. In claude.ai an organization admin adds it under Organization settings > Plugins & skills > Marketplaces, from a private copy (see claude.ai below). If your assistant has no plugins, add the **connector** by its URL instead, as for claude.ai and ChatGPT below. ### claude.ai In Settings, open Connectors and add a custom connector named **My Mapit** with the URL `https://api.mapit.me/mcp`. Then connect it and sign in with your Mapit account. **Team and Enterprise owners** can give the plugin to the whole organization: in Organization settings, open Plugins & skills, then Marketplaces, and add the GitHub repository that holds a copy of `mapit-iot/ai-plugin`. Anthropic accepts only private or internal repositories there, so copy it into a private repository of the organization first. Everyone else adds the connector as above. ### ChatGPT Add a custom connector (an app that uses MCP) named **My Mapit** with the URL `https://api.mapit.me/mcp`, and sign in with your Mapit account. Where custom connectors are in ChatGPT depends on your plan and app version. ### Claude Code Install the Mapit plugin from the [mapit-iot/ai-plugin](https://github.com/mapit-iot/ai-plugin) marketplace: ``` /plugin marketplace add mapit-iot/ai-plugin /plugin install mapit@mapit ``` Then run `/mcp`, choose **plugin:mapit:my-mapit** and sign in. The plugin also adds two skills that help the assistant answer questions about your bike and build ride totals. ### OpenAI Codex Install the plugin from the same [mapit-iot/ai-plugin](https://github.com/mapit-iot/ai-plugin) marketplace: ``` codex plugin marketplace add mapit-iot/ai-plugin codex plugin add mapit@mapit ``` Then sign in with your Mapit account the first time you use it. ### Any other MCP client Add a remote MCP server with the URL `https://api.mapit.me/mcp`. It uses the Streamable HTTP transport and OAuth sign-in: the client opens Mapit's sign-in page, you approve it, and it keeps a token, never your password. ``` https://api.mapit.me/mcp ``` ### What the assistant can and cannot do - **Read-only.** It can read your account, vehicles, subscription, where each vehicle last reported, and your routes and ride statistics. It cannot change anything, and it cannot send commands to your bike. - **Location and routes need your tick.** On the sign-in page you choose whether to share location and route history. If you leave them unticked, the assistant cannot see them. - **Last reported, not live.** A position is what the tracker last sent, and the assistant says when. It cannot follow your bike live. - **Your account only.** It sees your vehicles, as the Mapit app shows them. - **You stay in control.** See and end every connection at [login.mapit.me/connections](https://login.mapit.me/connections). It takes effect on the next request. Claude, ChatGPT and other assistants connected this way are on the [Approved apps](https://developers.mapit.me/approved-apps.md) list. Use is for your own personal, non-commercial purposes, under the [API terms of use](https://developers.mapit.me/terms.md) and the [API privacy notice](https://developers.mapit.me/privacy.md). ## Build with an AI coding agent Give your coding agent these addresses. Each docs page is also available as Markdown: add `.md` to its address. - [`https://developers.mapit.me/llms.txt`](https://developers.mapit.me/llms.txt): an index of every page, with a line on each. - [`https://developers.mapit.me/llms-full.txt`](https://developers.mapit.me/llms-full.txt): all the docs in one Markdown file. - [`https://developers.mapit.me/openapi.json`](https://developers.mapit.me/openapi.json): the OpenAPI description, with every endpoint, parameter and field. ### Instructions for the agent Paste this into your agent's instructions (for example `AGENTS.md` or `CLAUDE.md`) or at the start of a task: ``` You are writing code against the Mapit API (beta). Docs index: https://developers.mapit.me/llms.txt All docs in one file: https://developers.mapit.me/llms-full.txt OpenAPI spec: https://developers.mapit.me/openapi.json - Base URL: https://api.mapit.me/v1 - Auth: send a personal key as "Authorization: Bearer $MAPIT_KEY". Read the key from an environment variable. Never hard-code it, print it or log it. - Rate limit: 30 requests a minute per key or access token, for the REST API and the MCP connector. Bursts above it may be tolerated, never rely on them. On 429, wait Retry-After seconds. Poll /status at most once a minute. See https://developers.mapit.me/limits.md - Every 200 answer has an ETag: send it back in If-None-Match. 304 means nothing changed. - Version 1 only gains fields: ignore fields you do not know. - Ids and cursors are opaque: store them, never build or parse them. Follow nextCursor until it is null. - Positions are last reported, not live: show when (lastLocationAt). - Location and routes need permission on the key: 403 means it lacks it. - Read-only, except disconnecting apps and keys. Never call DELETE unless the user asks. - Personal, non-commercial use: the user's own vehicles only. - Python: use the aiomapit package instead of raw HTTP. ``` ### Python: aiomapit For Python, the fastest path is [aiomapit](https://pypi.org/project/aiomapit/), Mapit's official async client (Python 3.12 or newer). It is typed, handles paging and is what the [Home Assistant](https://developers.mapit.me/home-assistant.md) integration uses. Create a [personal key](https://developers.mapit.me/keys.md) first. ``` pip install aiomapit ``` ``` import asyncio, os from aiomapit import MapitClient async def main(): async with MapitClient(os.environ["MAPIT_KEY"]) as client: async for status in client.iter_statuses(): if status.state: print(status.vehicle_id, status.state.latitude, status.state.longitude) asyncio.run(main()) ``` Other languages can use [the reference](https://developers.mapit.me/reference.md) or the OpenAPI file to generate a client. --- Source: https://developers.mapit.me/home-assistant # Home Assistant Mapit's own Home Assistant integration puts each of your vehicles on the map as a device tracker, with sensors for its battery and when it last reported. > **Beta.** The Mapit API behind it is a beta, free for now. See the [beta terms](https://developers.mapit.me/terms.md). ## Install You need Home Assistant 2026.10 or newer, and a Mapit account with at least one vehicle. With [HACS](https://hacs.xyz/): 1. Add `https://github.com/mapit-iot/home-assistant-mapit` as a custom repository, with the category Integration. 2. Install **Mapit** and restart Home Assistant. HACS installs the [latest release](https://github.com/mapit-iot/home-assistant-mapit/releases/latest). 3. Go to **Settings > Devices & services > Add integration** and pick **Mapit**. 4. Sign in with your Mapit account and tick **Also allow vehicle location and last reported device status**. Home Assistant cannot show your vehicles without it. 5. The first time, `my.home-assistant.io` asks for your Home Assistant URL (it suggests `http://homeassistant.local:8123`). Enter the address you open Home Assistant at and press **Link account**. The address is stored only in that browser. 6. Home Assistant opens a **Name and assign** dialog that lists every vehicle, where you can choose an area for each. **Skip and finish** is fine too. Your vehicles appear. Without HACS, download the source of the [latest release](https://github.com/mapit-iot/home-assistant-mapit/releases/latest), not `main`, copy its `custom_components/mapit` folder into your Home Assistant `config/custom_components` folder, and restart Home Assistant. Home Assistant downloads `aiomapit` from PyPI on that first restart, so it needs internet access. Then continue from step 3. ## What you get Each vehicle becomes a device with these entities: | Entity | What it shows | | --- | --- | | Device tracker (the vehicle's name) | The last position reported. A vehicle that never reported a position shows _unknown_. | | Mapit battery | The tracker's own battery, not the vehicle's. | | Last communication | When the tracker last reported anything. | | Last location | When the position was reported. | | Odometer | The mileage stored in Mapit. | | Status | What the tracker last reported, as listed below. | | Vehicle voltage | The vehicle's supply seen by the tracker. Disabled by default: turn it on in the entity settings. | Everything is last reported, not live. The status shows one of these values, with the same labels as the Mapit app: - `at_rest`: **At rest**. The vehicle is parked. - `buzz`: **Vibration**. The tracker felt vibration while parked. - `moving`: **In transit**. The vehicle is moving. - `no_comms`: **Offline**. The tracker is not communicating. - `hibernation` and `hibernation_requested`: **Off**. Hibernating or about to, to save battery. - `tilt_detected`: **Fall detection**. The vehicle may have fallen. A vehicle that never reported, or reports a status not listed here, shows _unknown_. ## How it works - **No password in Home Assistant.** You sign in on Mapit's page and approve Home Assistant, as you would for any other app. Home Assistant keeps a token, never your password. - **You choose what it sees.** Location is a separate permission on the approval page. - **Disconnect from Mapit.** The connection appears on your connected apps page, where you can end it. - **Light.** It reads every vehicle's status in one request, about once a minute. ## Integrations that ask for your password Some community integrations sign in with your Mapit email and password. They hold your password, and they can stop working whenever the Mapit app changes. We recommend moving to the official integration and then changing your Mapit password. --- Source: https://developers.mapit.me/reference # API reference Base URL `https://api.mapit.me/v1`. Every request sends `Authorization: Bearer` with a [personal key](https://developers.mapit.me/keys.md) or an [OAuth](https://developers.mapit.me/oauth.md) access token. The machine-readable description is [openapi.json](https://developers.mapit.me/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/connections` (needs 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/status` (needs 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}/status` (needs 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}/routes` (needs 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}/stats` (needs 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 | | --- Source: https://developers.mapit.me/limits # Limits The numbers behind the [API terms of use](https://developers.mapit.me/terms.md). Mapit may change them to protect the service; this page always shows the current ones, and a change that is materially worse for you is announced as the terms describe. > **Beta.** Limits may be tightened or relaxed while Mapit learns how the API is used. ## Requests | Limit | Value | | --- | --- | | Per personal key or access token | 30 requests a minute, for both the REST API and the My Mapit connector (MCP). Over that, the API answers `429` with `Retry-After` in seconds. | | Per IP address | 1,000 requests in 5 minutes. Requests from addresses on AWS's IP reputation list are blocked. | | Sign-in pages, per IP address | 30 requests in 5 minutes to `/login` and `/oauth/register` on `login.mapit.me`. Over that, the request is refused with `429` for the rest of the window. | | Following your vehicles | Ask `https://api.mapit.me/v1/status` at most once a minute. It returns every vehicle in one request. | Short bursts above the per-key limit may be tolerated, but do not rely on them: Mapit may change limits, and tighten enforcement, at any time to protect the service. Using several keys, accounts or addresses to get around these limits is not allowed. ## Keys, connections and tokens | Item | How long it lasts | | --- | --- | | Personal key | One year from when you create it. Up to 10 keys per account. | | App connection | 30 days after the app last renewed it, and never more than one year after you signed in. | | Access token given to an app | 15 minutes. The app renews it on its own. | You can delete a key or disconnect an app at any time at [login.mapit.me/connections](https://login.mapit.me/connections). It takes effect on the next request. ## Sign-in | Item | Value | | --- | --- | | Sign-in session on the Mapit sign-in page | One hour. | | Failed password attempts in one sign-in flow | 5\. The last one ends that flow and you start again from the app. | | Failed password attempts per IP address | 20 in 15 minutes. Over that, sign-in is refused with `429` until the 15 minutes have passed. | | Failed sign-in attempts are counted for | 15 minutes. | --- Source: https://developers.mapit.me/versions # Versions and deprecation The version and deprecation policy behind the [API terms of use](https://developers.mapit.me/terms.md). The current version is `https://api.mapit.me/v1` (v1). > **Beta.** While the API is a beta, this policy is a goal, not a guarantee: Mapit may make a breaking change sooner, and will tell you on this site where it can. ## Policy - **v1 only gains fields.** Mapit does not remove or rename a field, or change what it means, within a version. Your code should ignore fields it does not know. - **Breaking changes get a new version**, such as `/v2`. - **Six months' notice** on this site before a version is retired. - Features labelled **Beta** may change or end without a new version. --- Source: https://developers.mapit.me/approved-apps # Approved apps The [API terms of use](https://developers.mapit.me/terms.md) allow your own scripts and the apps listed here. An app built for other Mapit customers that is not listed needs Mapit's prior written approval. This page is updated as apps are approved or removed. | App | How it connects | Official project | | --- | --- | --- | | Claude, ChatGPT and other AI assistants | Through the My Mapit connector (MCP). You sign in on Mapit's page and choose what the assistant may see. | Official (by Mapit): [My Mapit for Claude Code and Codex](https://github.com/mapit-iot/ai-plugin) | | Home Assistant | Mapit's own integration. See [Home Assistant](https://developers.mapit.me/home-assistant.md). | Official (by Mapit): [Mapit for Home Assistant](https://github.com/mapit-iot/home-assistant-mapit) | | Your own scripts | With a [personal key](https://developers.mapit.me/keys.md), for your own vehicles and personal use. | Official (by Mapit): [aiomapit](https://github.com/mapit-iot/aiomapit), the Python client | The projects marked Official are made and maintained by Mapit. Other projects that use the Mapit API are not endorsed by Mapit unless they are listed on this page. ## Ask for approval To build an app or service for other Mapit customers, write to [atencioncliente@mapit.me](mailto:atencioncliente@mapit.me) with what it does and what data it needs. An approved app follows the terms, reads only the data each customer allows, and gives customers its own privacy notice. --- Source: https://developers.mapit.me/terms # API terms of use These terms cover the Mapit API: `https://api.mapit.me/v1`, the My Mapit connector for AI assistants, personal keys and the apps you connect at `login.mapit.me`. They add to Mapit's [General Terms and Conditions](https://mapit.me/en/terms-and-conditions/). If the two disagree about the API, these terms apply; for everything else, the General Terms apply. Effective 17 November 2026. Last updated 17 November 2026. Provider: the Mapit company named in your contract, as set out in the General Terms (in Spain, Mapit IoT, S.L., calle Casp 172, 4B, 08013 Barcelona, NIF B-66716291). You accept these terms, and the [API privacy notice](https://developers.mapit.me/privacy.md), when you create a personal key or allow an app on the Mapit sign-in page. These terms refer to pages on this site, as published and updated from time to time: [Limits](https://developers.mapit.me/limits.md), [Approved apps](https://developers.mapit.me/approved-apps.md), [Versions](https://developers.mapit.me/versions.md) and the [API reference](https://developers.mapit.me/reference.md). Those pages are part of these terms. ## 1. Who may use the API - You may use the API if you have a Mapit account. You may read only your own account's data. - You can let an app read your data for you. You choose the app and what it may see when you connect it. - Your own scripts, and the apps listed on the [Approved apps](https://developers.mapit.me/approved-apps.md) page (such as Claude, ChatGPT and other AI assistants through the My Mapit connector, and Home Assistant), are approved. - Anything built for other Mapit customers, and not listed there, needs Mapit's prior written approval. Write to [atencioncliente@mapit.me](mailto:atencioncliente@mapit.me). An approved app must follow these terms, read only the data each customer allows, and give them its own privacy notice. - Mapit gives no keys to third parties to read other customers' data. Every key and connection belongs to one customer. ## 2. Personal, non-commercial use The API, the My Mapit connector and personal keys are for **your own personal, non-commercial use**: your own vehicles, your home automation and your own scripts. Without Mapit's prior written approval you must not use them to build a product or service for other people, resell or share access, or use them for a business. The apps on the Approved apps page are approved. ## 3. Keys and connections - Keep your keys secret, like a password. Do not put them in code you share, in screenshots or in public places. - Delete a key, or disconnect an app, as soon as you think someone else has it. You can do this at any time at [login.mapit.me/connections](https://login.mapit.me/connections). - A key keeps working after you change your Mapit password. Changing your password does not delete your keys or connections. Delete them yourself. - How long keys, connections and tokens last is on the [Limits](https://developers.mapit.me/limits.md) page. You are responsible for what is done with your keys and connections until you delete them. ## 4. Limits and fair use Use the API within the limits published on the [Limits](https://developers.mapit.me/limits.md) page. Mapit may change them to protect the service. Do not use several keys, accounts or IP addresses to get around them, and do not put so much load on the API that it harms the service for other customers. ## 5. What you must not do These rules add to the General Terms. You must not: - Read or try to read data of another Mapit customer without their permission, or collect data from the API in bulk for anyone other than the customer it belongs to. - Sell, rent or share access to the API, your keys or the data, or offer them as part of a paid service, without Mapit's written permission. - Try to get past the API's security. - Use the API where a wrong, late or missing answer could hurt someone, such as emergency response, collision detection or safety systems, or to find a stolen vehicle. Mapit's alerts are not an emergency service (see the General Terms), and the API is not one either. Use the Mapit app, and the police, for that. - Use the API to track a person without their knowledge, or in any way that breaks the law. ## 6. Data from the API - Location is the **last position the device reported**, not a live position. Each answer says when the position was recorded and when the device last talked to Mapit. A device with no signal, or switched off, keeps showing its last position. - Route history may not include every trip the Mapit app shows. - Distances, speeds and statistics come from GPS and the device. They can be wrong. Do not use them as legal or official evidence. - For now the API is provided as is and could break at any time. Mapit will strive not to let that happen, but does not promise that it will always be available, fast or free of errors. ## 7. Beta Anything this site labels **Beta**, which today includes the API, the My Mapit connector, personal keys and this site, is a service Mapit is testing with customers. For anything labelled Beta: - It may change or end, and Mapit may give notice on this site where it can. - There is no service level: Mapit does not promise that it is available, fast, complete or free of errors, and offers support on a best-effort basis. - Limits and policies on the pages these terms refer to may be tightened or relaxed while Mapit learns how it is used, and the version policy is a goal, not a guarantee. - Tell Mapit what you think at [atencioncliente@mapit.me](mailto:atencioncliente@mapit.me). Mapit may use your feedback freely, for any purpose, without owing you anything for it. When Mapit removes the Beta label from something, this section stops applying to it, and these terms do not change. ## 8. Changes to the API The [Versions](https://developers.mapit.me/versions.md) page sets out how the API is versioned and how long before a version is retired. Mapit may add features, and may remove one for security or legal reasons with the notice the General Terms require. ## 9. Suspension and ending access - Mapit may block a key, a connection or an IP address straight away if it breaks these terms, puts the service or other customers at risk, or looks compromised. Where it can, Mapit will tell you why. - If you seriously or repeatedly break these terms, Mapit may end your API access. The General Terms on ending the contract also apply. - When your Mapit account ends, your keys and connections stop working. - You can stop using the API at any time by deleting your keys and disconnecting your apps. ## 10. Liability The liability rules of the General Terms apply to the API, and so does the consumer protection law that applies to you. Mapit sets no separate liability limit for the API. In particular, Mapit is not responsible for what an app you connect does with your data, or for losses caused by keys you did not keep secret. ## 11. Changes to these terms and to the pages they refer to - Mapit may update these terms and the pages they refer to at any time. The dates at the top show the current version. - A change that is materially worse for customers, such as new charges or a removed feature, gets 30 days' notice by email and on this site. - Mapit does not charge for the API today. If Mapit introduces charges, it will publish them on this site and give 30 days' notice. Nothing is charged unless you accept. ## 12. Law, language and contact - The same law and courts apply as in the General Terms. - These terms are in English, Spanish and Portuguese. If they differ, the Spanish version applies, as in the General Terms. - Questions about the API: [atencioncliente@mapit.me](mailto:atencioncliente@mapit.me). About your data: see the [API privacy notice](https://developers.mapit.me/privacy.md). --- Source: https://developers.mapit.me/privacy # API privacy notice This notice explains what happens to your personal data when you use the Mapit API with a personal key or a connected app. It adds to Mapit's [Privacy Policy](https://mapit.me/en/privacy-policy/) and the data protection section of the [General Terms and Conditions](https://mapit.me/en/terms-and-conditions/), which cover everything else. Effective 17 November 2026. Last updated 18 November 2026. ## 1. Who is responsible The controller is the Mapit company named in your contract: in Spain, Mapit IoT, S.L., calle Casp 172, 4B, 08013 Barcelona, NIF B-66716291. You can reach Mapit's data protection officer at [gdpr@mapit.me](mailto:gdpr@mapit.me). ## 2. What the API returns The API only returns data from your own account, and only to a key or app you created or approved. It returns the same data the Mapit app shows you: | Data | Who can read it | | --- | --- | | Your name, email, language and time zone | Every key and connection | | Your vehicles: name, model, plate, kilometres, subscription status and end date | Every key and connection | | Last reported position, battery and device status, with the time they were recorded | Only if you ticked **location** | | Trips: start and end times, distance, duration, average and top speed, the route on a map, and ride statistics | Only if you ticked **route history** | The API never returns payment details, and it does not show Mapit's internal account, device or vehicle numbers. It uses codes that work only for your account. ## 3. Apps you connect - When you connect an app, such as Home Assistant or an AI assistant, Mapit sends it the data you allowed. From then on, that app's provider decides what to do with it. It is their own controller, and their privacy policy applies, not Mapit's. - Disconnecting an app stops new data from reaching it. It does not delete data the app already received. Ask the app's provider for that. - You can see and disconnect your apps and keys at any time at [login.mapit.me/connections](https://login.mapit.me/connections). ## 4. What Mapit records when you use the API ### Your keys and connections For each key or connection Mapit keeps: your account, the name you gave the key or the app's name, the permissions, when it was created, when it ends, and whether it was deleted. Keys and tokens are stored only as a one-way fingerprint (a hash), so Mapit cannot read them back. ### Request logs For each request Mapit records one line with: - the kind of request (for example "vehicle status"), not the full address; - the answer code (for example 200 or 429) and how long it took; - the kind of client: personal key, Home Assistant, Claude, ChatGPT, a program on your own computer or another app; - your Mapit account number (not for requests from AI assistants) and a short code that tells your keys and connections apart. The log does not contain the address you called, its parameters, your key or token, or the data returned. Mapit uses these logs to run the service, find faults and stop abuse. ### Sign-in When you sign in to manage keys or connect an app, the sign-in page passes your email and password to Amazon Cognito, the system that checks Mapit passwords. The password is never stored or logged. To stop password guessing, Mapit counts failed attempts for a short time (see the [Limits](https://developers.mapit.me/limits.md) page), keyed on a fingerprint of your IP address. Mapit also records each step of connecting an app (sign-in succeeded or failed, the permissions asked for and granted, the connection made, renewed or removed) with the kind of app, but not your account, email or IP address. ### Usage analytics Mapit uses PostHog, hosted in the EU, to count how many people use the API. It receives only these events, linked to your Mapit account number and not to your name or email: - an app was connected (the kind of app, its name and the permissions); - you opened the page to connect an app (the kind of app and the permissions it asked for); - a personal key was created (the permissions; never the key or its name); - a new key or connection was used for the first time (the kind of app, the kind of request and how long after it was made); - once a day for each kind of app you use (Home Assistant, a personal key, Claude, ChatGPT, a program on your computer or another app): the kinds of request it made that day, such as "vehicle status" or the name of an AI tool, and the name and version of the client software, such as `HomeAssistant/2026.8.2`. It is sent when the app next calls on a later day; - each request an AI assistant makes through the MCP connection (the tool's name, how long it took, whether it failed and how, the assistant's name and model, a conversation code, and the names, not the values, of what it asked for). PostHog does not receive your IP address, your location, your trips or any other data the API returns. Location lookup from IP is turned off. ## 5. Why Mapit does this - To give you the API you asked for: performance of your contract with Mapit. - Request logs, limits and security checks: to keep the service and your data safe and stop abuse. This is in Mapit's legitimate interest in running a secure service. - Usage analytics: to learn how the API is used and improve it. This is in Mapit's legitimate interest in understanding and improving the API. You can object at any time by writing to [gdpr@mapit.me](mailto:gdpr@mapit.me). ## 6. How long Mapit keeps it | Data | Kept for | | --- | --- | | Request logs | One month, then deleted automatically. | | Key and connection records | Until the key or connection would have ended (the [Limits](https://developers.mapit.me/limits.md) page says how long keys last), even if you delete it sooner, then deleted automatically. Backups of these records are kept for up to 35 more days. | | Sign-in session | As short as the [Limits](https://developers.mapit.me/limits.md) page says. | | Usage analytics in PostHog | No more than 12 months. | | Daily usage summary (the last day of use, until it is sent to PostHog) | Up to 400 days after the last call. | Your account, vehicle, location and trip data are kept as the [Privacy Policy](https://mapit.me/en/privacy-policy/) says. Using the API does not change that. ## 7. Who processes it for Mapit | Provider | What for | Where | | --- | --- | --- | | Amazon Web Services | Runs the API, sign-in, storage and logs | Ireland (EU), region eu-west-1 | | Amazon CloudFront and AWS WAF | Deliver requests and block abuse. They do not keep request logs for Mapit. | Servers near you in Europe or North America | | PostHog | Usage analytics | EU | Some of these providers handle data outside the European Economic Area: CloudFront servers in North America, and the US parent companies of AWS and PostHog. Mapit uses only providers that rely on the safeguards the GDPR requires for such transfers, such as the European Commission's standard contractual clauses or an adequacy decision. You can ask [gdpr@mapit.me](mailto:gdpr@mapit.me) for details. ## 8. Your rights You have the rights listed in the General Terms: access, correction, deletion, restriction, objection, portability, and not being subject to automated decisions. To use them, write to [gdpr@mapit.me](mailto:gdpr@mapit.me). You can complain to a data protection authority: in Spain the AEPD ([www.aepd.es](https://www.aepd.es/)), in Portugal the CNPD ([www.cnpd.pt](https://www.cnpd.pt/)). You do not need to contact Mapit first. ## 9. Changes If what the API records changes, Mapit will update this notice and its date before the change.