API for Partners (draft)

Before publishing

• The JSON API v1 exists (internal reference), but it is built for the Demostatics apps: tokens come from signing in as a user. Partner API keys do not exist yet — no issuance, scopes, usage metering or per-partner limits.
• Decide: base URL (e.g. https://api.demostatics.com/v1), rate limits per plan, terms of data use and redistribution, and the commercial offer.
• Publish only the read endpoints partners are meant to use; never document internal or worker endpoints.

Partners with API access can read Demostatics data from their own systems.

Getting access

TODO: API access is part of the TODO plan. Contact us to request a key; keys are shown once and can be revoked from the account.

Authentication

Send your key as a bearer token, and always ask for JSON:

GET /v1/reports?country_id=225&start_date=2026-01-01 HTTP/1.1
Host: api.demostatics.com
Authorization: Bearer <your key>
Accept: application/json

Responses

• Single item: { "data": { … } }
• Lists: { "data": [ … ], "meta": { "current_page", "last_page", "per_page", "total" } }
• Page through with ?page=; set ?per_page= from 1 to 50.
• Errors: { "message": "…" } with the HTTP status (401 bad key, 403 not allowed, 404 not found, 422 invalid parameters, 429 rate limited).

Endpoints

Endpoint	Returns	Filters
GET /v1/reports	Reports, newest first	region, subregion, country, state, city, category, subcategory, start/end date
GET /v1/database-items	Latest values, newest first	region … city, category, subcategory
GET /v1/regions … /cities	The geography hierarchy	parent id

TODO: confirm exact paths and parameter names against the final partner API.

Limits

TODO: requests per minute and per day for each plan; behaviour when exceeded (HTTP 429 with Retry-After).

Terms

Use of the API is governed by the Terms of Service and your agreement. TODO: attribution and redistribution rules.