mototrack 1.0.0__tar.gz

mototrack-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MotoTrack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mototrack-1.0.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: mototrack
+Version: 1.0.0
+Summary: Python client for the MotoTrack fleet-tracking API: vehicles, live positions, trips, events, streaming and webhooks.
+Author-email: MotoTrack <support@themototrack.com>
+License: MIT
+Project-URL: Homepage, https://themototrack.com
+Project-URL: Documentation, https://themototrack.com/developers
+Keywords: mototrack,gps,fleet,tracking,telematics,odoo,erp
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# MotoTrack Python SDK
+
+Pull your fleet's live tracking from [MotoTrack](https://themototrack.com) into Odoo, Django, a cron job or any other Python system.
+
+- One file, standard library only, Python 3.8+
+- Vehicles, latest and historical positions, trips, events, geofences
+- Push positions from your own devices
+- Live Server-Sent Events stream with automatic reconnect
+- Webhook signature verification
+- Automatic retry on rate limits (429) and gateway errors (502/503/504)
+
+## Install
+
+```bash
+pip install mototrack
+```
+
+Or copy `mototrack.py` into your project (it has no dependencies).
+
+## Get an API key
+
+In MotoTrack, open **Settings, Developer API** and create a key. Keys look like `mtk_live_...` and carry scopes:
+
+| Scope    | Allows                                   |
+|----------|------------------------------------------|
+| `read`   | every `GET` endpoint                     |
+| `stream` | the live event stream                    |
+| `ingest` | `push_positions()` (sending positions)   |
+
+Keep the key on your server. Never ship it in a browser or mobile app.
+
+## Quick start
+
+```python
+from mototrack import MotoTrack, ApiError
+
+mt = MotoTrack("mtk_live_...")
+
+print(mt.me()["account"]["name"])
+
+for row in mt.latest_positions():
+    pos = row["position"]
+    if pos:
+        print(row["plateNumber"], pos["lat"], pos["lng"], pos["speed"], "km/h")
+```
+
+## Reference
+
+All methods return plain dicts and lists decoded from the API's JSON. Times are ISO 8601 UTC strings (`"2026-11-14T08:30:00.000Z"`); wherever a method takes a time you may pass a string or a `datetime` (naive datetimes are read as UTC). Speeds are km/h.
+
+### `MotoTrack(api_key, base_url=..., stream_url=..., timeout=30, max_retries=3)`
+
+| Argument      | Default                                       |
+|---------------|-----------------------------------------------|
+| `base_url`    | `https://api.themototrack.com/api/v1`         |
+| `stream_url`  | `https://socket.themototrack.com/v1/stream`   |
+| `timeout`     | seconds per REST call                         |
+| `max_retries` | retries after 429, 502, 503, 504 or a network error; `0` disables |
+
+`mt.rate_limit` holds the last rate-limit headers seen: `{"limit": 600, "remaining": 598, "reset": 1794655800}` (`reset` is unix seconds).
+
+### Account
+
+| Method | Returns |
+|--------|---------|
+| `me()` | `{key: {id, name, prefix, scopes, createdAt}, account: {organizationId, name}, plan, limits: {requestsPerMinute, streamConnections}}` |
+
+### Vehicles
+
+| Method | Returns |
+|--------|---------|
+| `vehicles(page=1, limit=50, search=None)` | `{data: [Vehicle], pagination: {page, limit, total, totalPages}}`, `limit` at most 200 |
+| `all_vehicles(search=None, page_size=200)` | generator over every vehicle, fetching pages as needed |
+| `vehicle(vehicle_id)` | `Vehicle` |
+
+A **Vehicle** is `{id, plateNumber, type, make, model, year, color, fuelType, trackerId, driver: {id, name, phone} or None, status: {online, lastSeenAt, battery, externalVoltage}, position: Position or None, createdAt}`.
+
+### Positions
+
+| Method | Returns |
+|--------|---------|
+| `latest_positions()` | `[{vehicleId, plateNumber, online, lastSeenAt, position}]`, the cheapest way to poll a fleet |
+| `positions(vehicle_id, from_=None, to=None, limit=None, cursor=None)` | `{data: [Position], nextCursor, range: {from, to}}`; `from_` defaults to 24 h before `to`, `to` to now, `limit` at most 5000 |
+| `all_positions(vehicle_id, from_=None, to=None, page_size=5000)` | generator over every position in the range, following `nextCursor` |
+
+A **Position** is `{lat, lng, speed, heading, altitude, recordedAt}`.
+
+```python
+from datetime import datetime, timedelta, timezone
+
+end = datetime.now(timezone.utc)
+for p in mt.all_positions(vehicle_id, from_=end - timedelta(days=7), to=end):
+    print(p["recordedAt"], p["lat"], p["lng"])
+```
+
+### Trips, events, geofences
+
+| Method | Returns |
+|--------|---------|
+| `trips(vehicle_id, from_=None, to=None)` | `[Trip]`; default last 7 days, at most 31 days |
+| `events(vehicle_id=None, type=None, from_=None, to=None, limit=None)` | `[{id, vehicleId, plateNumber, type, lat, lng, occurredAt}]`, `limit` at most 500 |
+| `geofences()` | `[{id, name, shape, center, radiusMeters, polygon, createdAt}]` |
+| `geofence_events(geofence_id, from_=None, to=None, limit=None)` | entries and exits for one geofence |
+
+A **Trip** is `{id, vehicleId, startedAt, endedAt, durationSeconds, distanceKm, averageSpeed, maxSpeed, start: {lat, lng}, end: {lat, lng}}`.
+
+### Sending positions
+
+`push_positions(positions)` needs a key with the `ingest` scope. Each item needs `vehicleId` or `trackerId`, plus `lat` and `lng`; `speed`, `heading`, `altitude`, `satellites`, `battery` and `recordedAt` are optional. Lists longer than 100 are split into several calls and the results merged.
+
+```python
+result = mt.push_positions([
+    {"vehicleId": "3f2a9c1e-...", "lat": -1.9441, "lng": 30.0619, "speed": 42, "recordedAt": datetime.now(timezone.utc)},
+    {"trackerId": "864000000000000", "lat": -1.95, "lng": 30.06},
+])
+# {"accepted": 1, "discarded": 0, "errors": [{"index": 1, "code": "NOT_FOUND", "message": "..."}]}
+```
+
+A rejected item never raises. Check `errors`, whose `index` points into the list you passed.
+
+## Live stream
+
+The stream needs a key with the `stream` scope. It sends a `ready` frame, then the current position of every vehicle, then live events as they happen.
+
+```python
+def on_event(event):
+    if event["type"] == "vehicle.position":
+        d = event["data"]
+        print(event["vehicle"]["plateNumber"], d["lat"], d["lng"], d["speed"])
+    elif event["type"] == "geofence.entered":
+        print(event["vehicle"]["plateNumber"], "entered", event["data"]["geofenceName"])
+    # return False to stop listening
+
+mt.stream(on_event, events=["vehicle.position", "geofence.entered"], vehicle_ids=None)
+```
+
+Or as a generator (break out of the loop to stop):
+
+```python
+for event in mt.iter_events(events=["vehicle.online", "vehicle.offline"]):
+    print(event["vehicle"]["plateNumber"], event["type"])
+```
+
+| Event type | `data` |
+|------------|--------|
+| `ready` | (no `data`) the frame itself has `connectionId`, `vehicles: [{id, plateNumber}]`, `events` |
+| `vehicle.position` | `lat, lng, speed, heading, altitude, battery, recordedAt` |
+| `vehicle.online`, `vehicle.offline` | |
+| `geofence.entered`, `geofence.exited` | `geofenceId, geofenceName, lat, lng` |
+| `vehicle.overspeed.started`, `vehicle.overspeed.ended` | `speed, limit, lat, lng` |
+
+Every event other than `ready` is `{id, type, occurredAt, vehicle: {id, plateNumber}, data}`. The `ready` frame always lists the whole fleet; the `vehicle_ids` filter applies to the events that follow.
+
+**Reconnects.** After a dropped connection the SDK waits 5 s (or what the server suggests) and reconnects, receiving a fresh `ready` and current positions. `max_reconnects` (default 10) caps consecutive failures; pass `None` to retry forever. It never reconnects after `API_KEY_MISSING`, `API_KEY_INVALID`, `SCOPE_MISSING` or `SUBSCRIPTION_REQUIRED`; those raise `ApiError`. Each plan allows a fixed number of open streams (`me()["limits"]["streamConnections"]`).
+
+## Errors
+
+Every failed call raises `ApiError` (also importable as `ApiException`):
+
+```python
+try:
+    mt.vehicle("does-not-exist")
+except ApiError as e:
+    print(e.status, e.code, e.message)   # 404 NOT_FOUND Vehicle not found
+```
+
+| Status | `code` | Meaning |
+|--------|--------|---------|
+| 400 | `VALIDATION_ERROR` | a parameter is wrong (for example a trip span over 31 days) |
+| 401 | `API_KEY_MISSING`, `API_KEY_INVALID` | no key, or a revoked or mistyped one |
+| 402 | `SUBSCRIPTION_REQUIRED` | the account has no active subscription |
+| 403 | `SCOPE_MISSING` | the key lacks `read`, `stream` or `ingest` |
+| 404 | `NOT_FOUND` | no such vehicle or geofence on this account |
+| 429 | `RATE_LIMITED` | over the plan's requests per minute (retried automatically first) |
+| 500 | `INTERNAL` | something broke on our side |
+| 0 | `NETWORK_ERROR` | the API could not be reached (after retries) |
+
+Retries: a 429 waits for `Retry-After`; 502, 503, 504 and network errors back off exponentially (1 s, 2 s, 4 s, ...). A `push_positions()` call that timed out is not resent, because the server may already have stored it.
+
+## Webhooks
+
+MotoTrack can POST events to your server: online/offline, geofence and overspeed events, in the same `{id, type, occurredAt, vehicle, data}` shape as the stream (`vehicle.position` is stream-only, it would be far too chatty for webhooks). Each delivery carries `X-MotoTrack-Event`, `X-MotoTrack-Event-Id` and `X-MotoTrack-Signature: t=<unix seconds>,v1=<hex>`, where the hex is HMAC-SHA256 of `"<t>.<raw body>"` with your endpoint's signing secret.
+
+`verify_webhook(raw_body, signature_header, secret, tolerance=300)` checks the signature in constant time, rejects deliveries older than `tolerance` seconds, and returns the decoded event. It needs no API key and is available as a module function or `MotoTrack.verify_webhook`.
+
+```python
+import os
+from flask import Flask, abort, request
+from mototrack import WebhookVerificationError, verify_webhook
+
+app = Flask(__name__)
+SECRET = os.environ["MOTOTRACK_WEBHOOK_SECRET"]
+
+@app.post("/mototrack/webhook")
+def mototrack_webhook():
+    try:
+        event = verify_webhook(
+            request.get_data(),  # the raw bytes, not request.json
+            request.headers.get("X-MotoTrack-Signature", ""),
+            SECRET,
+        )
+    except WebhookVerificationError:
+        abort(400)
+
+    # Deliveries can repeat; use the event ID to process each one once.
+    if already_processed(event["id"]):
+        return "", 200
+
+    if event["type"] == "geofence.entered":
+        print(event["vehicle"]["plateNumber"], "arrived at", event["data"]["geofenceName"])
+    return "", 200
+```
+
+Answer with a 2xx quickly and do slow work in the background.
+
+## Examples
+
+`examples/odoo_sync.py` keeps an ERP table in step with the fleet, either polling every 30 s or listening to the stream:
+
+```bash
+MOTOTRACK_API_KEY=mtk_live_... python examples/odoo_sync.py poll
+MOTOTRACK_API_KEY=mtk_live_... python examples/odoo_sync.py stream
+```
+
+## License
+
+MIT

mototrack-1.0.0/README.md

@@ -0,0 +1,227 @@
+# MotoTrack Python SDK
+
+Pull your fleet's live tracking from [MotoTrack](https://themototrack.com) into Odoo, Django, a cron job or any other Python system.
+
+- One file, standard library only, Python 3.8+
+- Vehicles, latest and historical positions, trips, events, geofences
+- Push positions from your own devices
+- Live Server-Sent Events stream with automatic reconnect
+- Webhook signature verification
+- Automatic retry on rate limits (429) and gateway errors (502/503/504)
+
+## Install
+
+```bash
+pip install mototrack
+```
+
+Or copy `mototrack.py` into your project (it has no dependencies).
+
+## Get an API key
+
+In MotoTrack, open **Settings, Developer API** and create a key. Keys look like `mtk_live_...` and carry scopes:
+
+| Scope    | Allows                                   |
+|----------|------------------------------------------|
+| `read`   | every `GET` endpoint                     |
+| `stream` | the live event stream                    |
+| `ingest` | `push_positions()` (sending positions)   |
+
+Keep the key on your server. Never ship it in a browser or mobile app.
+
+## Quick start
+
+```python
+from mototrack import MotoTrack, ApiError
+
+mt = MotoTrack("mtk_live_...")
+
+print(mt.me()["account"]["name"])
+
+for row in mt.latest_positions():
+    pos = row["position"]
+    if pos:
+        print(row["plateNumber"], pos["lat"], pos["lng"], pos["speed"], "km/h")
+```
+
+## Reference
+
+All methods return plain dicts and lists decoded from the API's JSON. Times are ISO 8601 UTC strings (`"2026-11-14T08:30:00.000Z"`); wherever a method takes a time you may pass a string or a `datetime` (naive datetimes are read as UTC). Speeds are km/h.
+
+### `MotoTrack(api_key, base_url=..., stream_url=..., timeout=30, max_retries=3)`
+
+| Argument      | Default                                       |
+|---------------|-----------------------------------------------|
+| `base_url`    | `https://api.themototrack.com/api/v1`         |
+| `stream_url`  | `https://socket.themototrack.com/v1/stream`   |
+| `timeout`     | seconds per REST call                         |
+| `max_retries` | retries after 429, 502, 503, 504 or a network error; `0` disables |
+
+`mt.rate_limit` holds the last rate-limit headers seen: `{"limit": 600, "remaining": 598, "reset": 1794655800}` (`reset` is unix seconds).
+
+### Account
+
+| Method | Returns |
+|--------|---------|
+| `me()` | `{key: {id, name, prefix, scopes, createdAt}, account: {organizationId, name}, plan, limits: {requestsPerMinute, streamConnections}}` |
+
+### Vehicles
+
+| Method | Returns |
+|--------|---------|
+| `vehicles(page=1, limit=50, search=None)` | `{data: [Vehicle], pagination: {page, limit, total, totalPages}}`, `limit` at most 200 |
+| `all_vehicles(search=None, page_size=200)` | generator over every vehicle, fetching pages as needed |
+| `vehicle(vehicle_id)` | `Vehicle` |
+
+A **Vehicle** is `{id, plateNumber, type, make, model, year, color, fuelType, trackerId, driver: {id, name, phone} or None, status: {online, lastSeenAt, battery, externalVoltage}, position: Position or None, createdAt}`.
+
+### Positions
+
+| Method | Returns |
+|--------|---------|
+| `latest_positions()` | `[{vehicleId, plateNumber, online, lastSeenAt, position}]`, the cheapest way to poll a fleet |
+| `positions(vehicle_id, from_=None, to=None, limit=None, cursor=None)` | `{data: [Position], nextCursor, range: {from, to}}`; `from_` defaults to 24 h before `to`, `to` to now, `limit` at most 5000 |
+| `all_positions(vehicle_id, from_=None, to=None, page_size=5000)` | generator over every position in the range, following `nextCursor` |
+
+A **Position** is `{lat, lng, speed, heading, altitude, recordedAt}`.
+
+```python
+from datetime import datetime, timedelta, timezone
+
+end = datetime.now(timezone.utc)
+for p in mt.all_positions(vehicle_id, from_=end - timedelta(days=7), to=end):
+    print(p["recordedAt"], p["lat"], p["lng"])
+```
+
+### Trips, events, geofences
+
+| Method | Returns |
+|--------|---------|
+| `trips(vehicle_id, from_=None, to=None)` | `[Trip]`; default last 7 days, at most 31 days |
+| `events(vehicle_id=None, type=None, from_=None, to=None, limit=None)` | `[{id, vehicleId, plateNumber, type, lat, lng, occurredAt}]`, `limit` at most 500 |
+| `geofences()` | `[{id, name, shape, center, radiusMeters, polygon, createdAt}]` |
+| `geofence_events(geofence_id, from_=None, to=None, limit=None)` | entries and exits for one geofence |
+
+A **Trip** is `{id, vehicleId, startedAt, endedAt, durationSeconds, distanceKm, averageSpeed, maxSpeed, start: {lat, lng}, end: {lat, lng}}`.
+
+### Sending positions
+
+`push_positions(positions)` needs a key with the `ingest` scope. Each item needs `vehicleId` or `trackerId`, plus `lat` and `lng`; `speed`, `heading`, `altitude`, `satellites`, `battery` and `recordedAt` are optional. Lists longer than 100 are split into several calls and the results merged.
+
+```python
+result = mt.push_positions([
+    {"vehicleId": "3f2a9c1e-...", "lat": -1.9441, "lng": 30.0619, "speed": 42, "recordedAt": datetime.now(timezone.utc)},
+    {"trackerId": "864000000000000", "lat": -1.95, "lng": 30.06},
+])
+# {"accepted": 1, "discarded": 0, "errors": [{"index": 1, "code": "NOT_FOUND", "message": "..."}]}
+```
+
+A rejected item never raises. Check `errors`, whose `index` points into the list you passed.
+
+## Live stream
+
+The stream needs a key with the `stream` scope. It sends a `ready` frame, then the current position of every vehicle, then live events as they happen.
+
+```python
+def on_event(event):
+    if event["type"] == "vehicle.position":
+        d = event["data"]
+        print(event["vehicle"]["plateNumber"], d["lat"], d["lng"], d["speed"])
+    elif event["type"] == "geofence.entered":
+        print(event["vehicle"]["plateNumber"], "entered", event["data"]["geofenceName"])
+    # return False to stop listening
+
+mt.stream(on_event, events=["vehicle.position", "geofence.entered"], vehicle_ids=None)
+```
+
+Or as a generator (break out of the loop to stop):
+
+```python
+for event in mt.iter_events(events=["vehicle.online", "vehicle.offline"]):
+    print(event["vehicle"]["plateNumber"], event["type"])
+```
+
+| Event type | `data` |
+|------------|--------|
+| `ready` | (no `data`) the frame itself has `connectionId`, `vehicles: [{id, plateNumber}]`, `events` |
+| `vehicle.position` | `lat, lng, speed, heading, altitude, battery, recordedAt` |
+| `vehicle.online`, `vehicle.offline` | |
+| `geofence.entered`, `geofence.exited` | `geofenceId, geofenceName, lat, lng` |
+| `vehicle.overspeed.started`, `vehicle.overspeed.ended` | `speed, limit, lat, lng` |
+
+Every event other than `ready` is `{id, type, occurredAt, vehicle: {id, plateNumber}, data}`. The `ready` frame always lists the whole fleet; the `vehicle_ids` filter applies to the events that follow.
+
+**Reconnects.** After a dropped connection the SDK waits 5 s (or what the server suggests) and reconnects, receiving a fresh `ready` and current positions. `max_reconnects` (default 10) caps consecutive failures; pass `None` to retry forever. It never reconnects after `API_KEY_MISSING`, `API_KEY_INVALID`, `SCOPE_MISSING` or `SUBSCRIPTION_REQUIRED`; those raise `ApiError`. Each plan allows a fixed number of open streams (`me()["limits"]["streamConnections"]`).
+
+## Errors
+
+Every failed call raises `ApiError` (also importable as `ApiException`):
+
+```python
+try:
+    mt.vehicle("does-not-exist")
+except ApiError as e:
+    print(e.status, e.code, e.message)   # 404 NOT_FOUND Vehicle not found
+```
+
+| Status | `code` | Meaning |
+|--------|--------|---------|
+| 400 | `VALIDATION_ERROR` | a parameter is wrong (for example a trip span over 31 days) |
+| 401 | `API_KEY_MISSING`, `API_KEY_INVALID` | no key, or a revoked or mistyped one |
+| 402 | `SUBSCRIPTION_REQUIRED` | the account has no active subscription |
+| 403 | `SCOPE_MISSING` | the key lacks `read`, `stream` or `ingest` |
+| 404 | `NOT_FOUND` | no such vehicle or geofence on this account |
+| 429 | `RATE_LIMITED` | over the plan's requests per minute (retried automatically first) |
+| 500 | `INTERNAL` | something broke on our side |
+| 0 | `NETWORK_ERROR` | the API could not be reached (after retries) |
+
+Retries: a 429 waits for `Retry-After`; 502, 503, 504 and network errors back off exponentially (1 s, 2 s, 4 s, ...). A `push_positions()` call that timed out is not resent, because the server may already have stored it.
+
+## Webhooks
+
+MotoTrack can POST events to your server: online/offline, geofence and overspeed events, in the same `{id, type, occurredAt, vehicle, data}` shape as the stream (`vehicle.position` is stream-only, it would be far too chatty for webhooks). Each delivery carries `X-MotoTrack-Event`, `X-MotoTrack-Event-Id` and `X-MotoTrack-Signature: t=<unix seconds>,v1=<hex>`, where the hex is HMAC-SHA256 of `"<t>.<raw body>"` with your endpoint's signing secret.
+
+`verify_webhook(raw_body, signature_header, secret, tolerance=300)` checks the signature in constant time, rejects deliveries older than `tolerance` seconds, and returns the decoded event. It needs no API key and is available as a module function or `MotoTrack.verify_webhook`.
+
+```python
+import os
+from flask import Flask, abort, request
+from mototrack import WebhookVerificationError, verify_webhook
+
+app = Flask(__name__)
+SECRET = os.environ["MOTOTRACK_WEBHOOK_SECRET"]
+
+@app.post("/mototrack/webhook")
+def mototrack_webhook():
+    try:
+        event = verify_webhook(
+            request.get_data(),  # the raw bytes, not request.json
+            request.headers.get("X-MotoTrack-Signature", ""),
+            SECRET,
+        )
+    except WebhookVerificationError:
+        abort(400)
+
+    # Deliveries can repeat; use the event ID to process each one once.
+    if already_processed(event["id"]):
+        return "", 200
+
+    if event["type"] == "geofence.entered":
+        print(event["vehicle"]["plateNumber"], "arrived at", event["data"]["geofenceName"])
+    return "", 200
+```
+
+Answer with a 2xx quickly and do slow work in the background.
+
+## Examples
+
+`examples/odoo_sync.py` keeps an ERP table in step with the fleet, either polling every 30 s or listening to the stream:
+
+```bash
+MOTOTRACK_API_KEY=mtk_live_... python examples/odoo_sync.py poll
+MOTOTRACK_API_KEY=mtk_live_... python examples/odoo_sync.py stream
+```
+
+## License
+
+MIT