Skip to main content

aiomapit: the official Python client for the Mapit API

Made and maintained by Mapit. Mapit lists its official and approved apps at https://developers.mapit.me/approved-apps. Other projects that use Mapit are not endorsed by Mapit unless they are listed there.

Async Python client for the Mapit API (https://api.mapit.me/v1): the account, vehicles, last reported position and routes that the Mapit app shows. Read-only, apart from disconnecting apps and keys (delete_connection, which needs the Manage connections permission). Built on aiohttp, fully typed. Used by the Home Assistant integration.

Beta, free for now. The Mapit API it talks to is a beta: it may change or stop, it has no uptime promise, and Mapit does not charge for it today. This library may need updates to follow it. Do not rely on it for emergencies or to recover a stolen bike: use the Mapit app. Use is subject to the Mapit API Terms of Use and Privacy Notice, for personal, non-commercial use.

pip install aiomapit

Python 3.12 or newer.

A personal key (your own scripts)

You need a Mapit account. Create a key at https://login.mapit.me/connections and pass it as the token. Location, route history and managing connections each need their own permission, ticked when the key is created (see personal keys).

import asyncio

from aiomapit import MapitClient


async def main() -> None:
    async with MapitClient("mapit_...") 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())

A token callback (apps that do OAuth themselves)

This is for apps that Mapit has approved (see Approved apps); anything built for other Mapit customers needs Mapit's written approval. The OAuth flow itself is described at https://developers.mapit.me/oauth. The library has no OAuth logic. Give it an async callable that returns a valid access token; it is called before every request, so it may refresh. Share your own aiohttp.ClientSession:

async def token() -> str:
    await oauth_session.async_ensure_token_valid()
    return oauth_session.token["access_token"]


client = MapitClient(token, session=session, user_agent="my-app/1.0")
vehicles = [v async for v in client.iter_vehicles()]

Without session, the client creates one and closes it in close() (or when leaving async with). With one, the session stays yours.

What it covers

Method Endpoint
get_me() (an Account with id, name, email; id is stable across email changes) GET /me
get_summary(vehicle_cursor=, transfer_cursor=) GET /summary
get_vehicles_page(cursor), iter_vehicles() GET /vehicles
get_vehicle(id), get_subscription(id) GET /vehicles/{id}, .../subscription
get_statuses_page(cursor), iter_statuses(), get_vehicle_status(id) (Location permission) GET /status, /vehicles/{id}/status
get_routes_page(id, day=, start=, end=, ...), iter_routes(id, ...) (Route history permission) GET /vehicles/{id}/routes
get_route(id, route_id, geometry=, simplify=) (Route history) GET /vehicles/{id}/routes/{route_id}
get_ride_stats(id, start, end, timezone=) (Route history) GET /vehicles/{id}/stats
get_connections(), delete_connection(id) GET, DELETE /me/connections (a personal key with "Manage connections")

Ids and cursors are opaque: pass them back as you got them. iter_* follow the cursors for you. The API allows 30 requests a minute per key or token, and positions are what the device last reported, so poll iter_statuses() once a minute at most.

Every get_* returns a Response with data (a frozen dataclass, snake_case fields), not_modified and etag.

ETag and 304

The client remembers the ETag of what it fetched (in memory, per URL and query) and sends it as If-None-Match. On 304 you get the earlier object back with not_modified=True:

res = await client.get_vehicle_status(vehicle_id)
if not res.not_modified:
    update(res.data)

The cache key includes the token, so two tokens never share an object; a refreshed OAuth token starts with a fresh cache. A 304 saves bandwidth and parsing, not quota: it still counts towards the 30 requests a minute. The routes list without a day or start/end is "the last 30 days to now" and never answers 304.

Errors

All derive from MapitError, which has status, title and detail from the application/problem+json body.

Raised When
MapitAuthError 401: missing, expired or revoked token
MapitScopeError 403 insufficient_scope; .scope is the missing scope
MapitNotFound 404: also for a foreign or unknown id
MapitRateLimited 429; .retry_after in seconds, or None
MapitConnectionError 5xx, timeout, network failure
MapitResponseError a 2xx answer that is not valid JSON or lacks the expected fields

Other statuses (such as 400 for a bad filter) raise MapitError itself. The client never retries: back off on MapitRateLimited and MapitConnectionError yourself.

Development

uv sync
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest

Help

Docs and API reference: https://developers.mapit.me. Questions: atencioncliente@mapit.me.

MIT licence.

Metadata

Release files for aiomapit 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiomapit 0.1.1
File Size Uploaded Provenance Actions
aiomapit-0.1.1.tar.gz 103.4 kB With provenance Details for aiomapit-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiomapit 0.1.1
File Interpreter ABI Platform Actions
aiomapit-0.1.1-py3-none-any.whl Python 3 none any Details for aiomapit-0.1.1-py3-none-any.whl

Total release size: 116.8 kB

Release files / aiomapit-0.1.1.tar.gz

Download URL aiomapit-0.1.1.tar.gz
Size 103.4 kB
Tags Source
SHA-256 checksum
How to use checksums
8b29b6aab060f51b86710893a4be56b3c1530a571b0a785902ba28e6aabf1428
BLAKE2b-256 checksum
How to use checksums
1c45366b40b7751602a4ff53c55ed4f7b6fc346b536b9312efe86b4693886980
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / aiomapit-0.1.1-py3-none-any.whl

Download URL aiomapit-0.1.1-py3-none-any.whl
Size 13.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c6addcfe2480dba7d8e520b0e9254d5dad7c4ef7c8e21430623f7b51571cf900
BLAKE2b-256 checksum
How to use checksums
568ab977d108bb9f84b2724fa30aa8e57982e1fb772edc06cba75419967d3966
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for aiomapit 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiomapit-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page