Miri Data API
Documentation

Welcome to the Miri API documentation. This guide provides information on how to use our RESTful API to retrieve environmental data from our network of devices.

General

General Info

1. Acceptable Use

The API must be used only for lawful purposes and in ways that do not disrupt service performance or violate applicable regulations. Activities such as abuse, scraping beyond rate limits, reverse-engineering, or attempting to bypass authentication are strictly prohibited.

2. Account Responsibility

The current version of the API is Miri API v1.0.

All endpoints are versioned to ensure backward compatibility as new features and improvements are introduced.

When breaking changes are required, they will be released under a new version.

Base URL

https://api.miri.africa/api/v1

3. Response Formats

The Miri API supports multiple response formats to fit different workflows and data pipelines.

JSON (Default)

  • Ideal for web applications and backend services
  • Structured and easy to parse
  • Returned by default if no format is specified

CSV

  • Best for spreadsheets and data analysis tools
  • Flattened structure for easy ingestion
  • Includes a location_id or device_id column where applicable

XLSX

  • Excel-compatible format
  • Suitable for reporting and offline analysis
  • Preserves tabular structure for multiple variables

Response format can be specified using the ?format query parameter.

4. Authentication

To access the API, you must include a valid api_key in the query parameters of every request. You can obtain your API Key from your account dashboard. Query Parameter: ?api-key=YOUR_API_KEY

Example

https://api.miri.africa/api/v1/air-data?api-key=YOUR_API_KEY

5. Limits

In order to maintain high API throughput, availability and quality of the service the API access is rate-limited.

Default rate limit per apikey is 100 API requests per day for all users.

All the HTTP requests are counted towards the limit, regardless of whether the request succeeded or not. Each request decrements the currently available limit by 1. The counters are reset each day at midnight UTC (the daily limit) and every full minute (the minute limit).

In case of exceeding the limit API request will returnHTTP 429 - Too Many Requests.

If you need an increased limit or want to use our data in a commercial project please contact us.

6. Plans

FREE

  • Designed for small-scale projects and personal use
  • Basic API access with standard performance
  • Limited data history (up to 1 year)
  • Fixed rate limits for fair usage
  • 100,000 credits / month

STANDARD

  • Built for growing products and production-ready applications
  • Basic customer support
  • Limited historical data access (up to 3 years)
  • No fixed call rate limits
  • Scales with available credits
  • 1,000,000 credits / month

EDUCATION

  • Designed for research-focused and large-scale academic use
  • Priority customer support
  • Extended historical data access (up to 10 years)
  • Unlimited call rate
  • High-throughput request handling
  • 2,500,000 credits / month

ENTERPRISE

  • Designed for large-scale organizations and enterprise workloads
  • Priority customer support with dedicated assistance
  • Full historical data access
  • Unlimited call rate
  • On-demand climate reports and advanced analytics
  • 7,500,000 credits / month

7. Language

Some API endpoints return textual content, e.g. description of current air quality. Such texts are translated and returned in a language according to user preference.

To select API content language you should include anAccept-LanguageHTTP header in your request with value set to desired language.

Currently supported languages are:
English ("en" - default)Polish ("pl")

8. Errors

Correctly issued API requests result in 200 OK HTTP status and a JSON content. Otherwise an HTTP error code status is returned, depending on situation. Table below explains it in detail:

CodeDescription
400Bad Request — Your request has invalid parameters.
401Unauthorized — Your API key is invalid or missing.
429Too Many Requests — You have exceeded your rate limit.
500Internal Server Error — Something went wrong on our end.

9. Time

All the time values that occur in the API (both as query parameters and as returned payload fields) are ISO8601 timestamps according toUTC timezone e.g. 2018-08-24T08:24:48.652Z.

Average measurements that are calculated for particular period of time (e.g. hourly averages) are returned along with that time period. This period is given as a pair of attributes fromDateTime and tillDateTime and represents a left-closed and right-open time interval [fromDateTime, tillDatetime).

10. Coordinates

All coordinates that occur in the API (both as query parameters and as returned payload fields) are according to WGS 84 standard.

Coordinates are a pair of numbers named latitude (or lat) and longitude (or lng) and representdecimal degrees i.e. degrees without minutes or seconds, but instead as floating point numbers with fractional part representing fraction of a degree.

  • Latitude (lat) range:-90.0 to +90.0
  • Longitude (lng) range:-180.0 to +180.0

11. Caching

Caching is applied to selected API endpoints to improve performance and reduce response times during repeated requests.

Currently, caching is enabled for the Air Data endpoints andInstallations endpoints. Cached responses are stored up to a maximum size of 23 MB. Once this limit is reached, older cache entries may be invalidated to accommodate new responses.

Each cached response has a Time-To-Live (TTL) of 1 hour. After the TTL expires, the cached data is considered stale and will be refreshed upon the next request.

Caching is managed server-side and requires no additional configuration from API consumers.

Developers should note that responses served within the TTL window may not reflect real-time updates. Applications requiring the most recent data should account for the 1-hour cache duration when designing their systems.

In case of applications displaying data continuously we recommend caching API responses in local storage and refreshing them periodically.

12. Compatibility

Wherever possible, this API will be maintained in a backwards compatible manner. JSON responses have following stability guarantees:

  • Properties of JSON objects will continue to have same name and value type

  • Properties marked as mandatory will always be returned and will never be removed from the API

  • Properties marked as optional may or may not be returned by the API and as such may be removed from the API permanently

  • Dynamic structures like arrays and maps may or may not contain some elements; in particular they may be empty sometimes

  • New properties may be added to the responses at any time, but they will not collide with existing properties, nor alter their meaning

Terms of Use

1. Acceptable Use

The API must be used only for lawful purposes and in ways that do not disrupt service performance or violate applicable regulations. Activities such as abuse, scraping beyond rate limits, reverse-engineering, or attempting to bypass authentication are strictly prohibited.

2. Account Responsibility

Users are responsible for all activity carried out using their API keys. API keys must be kept secure and should never be exposed in client-side code, public repositories, or shared with unauthorized parties.

3. Data Usage & Attribution

Users are responsible for all activity carried out using their API keys. API keys must be kept secure and should never be exposed in client-side code, public repositories, or shared with unauthorized parties.

4. Rate Limits & Fair Usage

Each plan has defined rate limits to ensure fair access for all users. Exceeding these limits may result in temporary throttling, degraded performance, or suspension. Persistent abuse can lead to permanent revocation of access.

5. Service Availability

While we strive for high availability, the API is provided on an “as-is” basis. Planned maintenance, upgrades, or unexpected outages may occur. We do not guarantee uninterrupted service.

6. Data Accuracy Disclaimer

Environmental and air-quality data is provided for informational and analytical purposes only. It should not be used as the sole basis for safety-critical, medical, or legal decisions without independent verification.

7. Termination & Suspension

Miri reserves the right to suspend or terminate API access at any time if these terms are violated, or if usage poses a risk to system stability, security, or other users.

Caching

1. What Is Cached?

Frequently requested data—such as recent weather conditions, air-quality indexes, or commonly accessed locations—may be cached to improve performance and reduce response times.

2. Cache Duration (TTL)

Cached responses include a Time-To-Live (TTL) value indicating how long the data remains valid. TTL varies depending on the endpoint: Real-time data: shorter TTL Historical or aggregated data: longer TTL

3. Cache Headers

API responses may include standard HTTP caching headers such as:

  • Cache-Control
  • ETag
  • Last-Modified

These headers help clients determine whether cached data can be reused or must be refreshed.

4. Client Side Caching

Clients are encouraged to cache responses locally when appropriate, especially for dashboards and analytics applications, to reduce API calls and stay within rate limits.

5. Cache Invalidation

Caches are automatically invalidated when new data becomes available or when critical updates are applied. Some endpoints may always bypass caching to ensure the most accurate real-time results.

6. No Cache Endpoints

Certain endpoints—such as live alerts or emergency environmental updates—are explicitly marked as non-cacheable to guarantee up-to-date information.

7. Performance & Cost Benefits

Proper caching reduces latency, improves user experience, lowers bandwidth usage, and helps users stay within their plan limits.