# Introduction
Welcome to the BreezoMeter API documentation. BreezoMeter’s Air Quality, Pollen, and Weather API endpoints serve current conditions, forecasts, and historical data. Breezometer’s Air-Quality Heatmap API lets you visualize local air quality information as map overlays.
The APIs are designed to easily integrate with your services and products. The APIs use REST (opens new window) architecture to expose endpoints via consistent and predictable URL schema. Each URL scheme, lets you executes a query that return either data, or a descriptive error message, alongside a proper HTTP status code.
For further information, questions, and comments please contact us .
# Schema
You access the API over the HTTPs protocol.
All responses, including error messages, are returned as JSON (opens new window) objects.
The API sends and receives timestamps in ISO 8601 (opens new window) YYYY-MM-DDTHH:MM:SSZ format.
# API Requests
# Data
The base URL for Air Quality, Pollen, and Weather data APIs is:
https://api.breezometer.com/
# Tiles
The base URL for the Heatmap Tile Overlay API is:
https://tiles.breezometer.com/
For the full path and relevant mandatory and optional parameters for a specific API endpoint, see the section that describes it.
# API Responses
# Data APIs
This example shows the structure of the JSON object that the Air Quality, Pollen, and Weather APIs return:
"metadata" : null , "error" : null }Each object contains the following fields:
null. For more information, see Metadata section.
Unsuccessful requests return
null. Depending on the request type, the data field may contain either a single object, or an array of objects.
For more information, see Request Types section.
Successful requests return
null.
For more information, see Error Response Body section.
# Request Types
There are two type of requests, which results in different response type under the data field.
While the first returns a single object, the second returns an array of objects.
# Single Object
Requests that query for information on a specific date and time return a single object under the data field. This include requests to get data from the current conditions endpoint, or getting data from the historical, or forecast endpoints, using the datetime parameter.
This type of request demonstrate the following response:
"metadata" : null , "error" : null }# Array of Objects
Requests that query for information on any number of hours, or a range of date and times return an array of objects under the data field. This include requests to get data from the historical, or forecast endpoints, using the hours or start_datetime and end_datetime parameters.
This type of request demonstrate the following response:
"metadata" : null , ] , "error" : null }# Heatmap Tiles API
Requests to the Heatmap Tile Overlay API return a collection of image tiles that can be overlayed over a map. Each tile is a 256 x 256 pixel PNG image.
# Authentication
To access API endpoints, you must include an API key with your requests. Every BreezoMeter account is assigned an API Key. The key stores permissions, rate limits, daily quota, API usage, and billing information associated with an account. To send an authenticated API request, you add the API key parameter and include your key to the request URL.
https://api.breezometer.com/air-quality/...?key=YOUR_API_KEY&...
Requests without an API Key, return this HTTP 403 - Forbidden response:
You can sign up and get your API Key from the BreezoMeter Account Dashboard (opens new window)
WARNING
Note:
Once you have generated your key it is important to keep it secure. Each key uniquely identifies and grants access to a BreezoMeter account. This means that anybody with your key can use it without your knowledge. In the event that your account is compromised, please contact BreezoMeter immediately.
# Access Permissions and Limits
Your API Key indicates the permissions associated with your account. These permissions grant access to specific:
- APIs and Endpoints
- Features
- Time periods in Forecast and History requests
- Country information
Checking your account permissions can be done in your account settings page (opens new window)
To resolve permissions related issues, or to ask for higher level of permissions than your account currently has, please
contact us
.
# How API Usage is Counted
# Data API - Queries and Objects
Each successful request to the BreezoMeter’s Air-Quality, Pollen, and Weather APIs is counted as a single query. A query can return single or multiple objects. A query that requests for information for a specific date and time, such as the current conditions, or specific date and time in the past or future, returns a single object.
Requests for information over a time period, such as X number of hours of Forecast data, or Historical data between two dates, is returned as multiple objects, depending on the length of the time interval queried.
For example, suppose you created a single API request to the Air Quality API’s Hourly Historical Data endpoint. Your query requests one week of historical data. The query returns a JSON file with 168 objects. This is the maximum number of objects returned for a single week. Each object returned by this query will be counted against your daily quota.
As the number of objects returned by a query is subject to rate limits, make sure to check Rate Limits and Max Range Limit for detailed explanations.
# Heatmap API - Tiles and Objects
Any successful Heatmap Tile Overlay API request returns multiple tiles. For daily quota and billing purposes, these tiles are counted as objects, based on the ratio as set in your plan.
# Daily Object Quota
Every BreezoMeter account is restricted to a specific number of objects it can receive on a daily basis. Depending on your account type, exceeding the quota has the following results:
- Free Account (Evaluation): Cannot performing additional requests until midnight at the following day.
- Paid Account: Charged additional fees based on the total number of objects exceeded in a day in comparison to the account’s daily quota.
Checking your account daily quota of objects can be done in your account settings page (opens new window)
# Rate Limits
The BreezoMeter API rate limits are determined according to the following criteria:
- Queries per Second (QPS): Sets the maximum number of queries sent per second for the account and its associated API Keys.
- Objects per Second (OPS): Sets the maximum number of objects queried per second for the account and its associated API Keys.
Every BreezoMeter account is assigned with a specific QPS and OPS limits. Since exceeding your assigned rate limits will result in disabling your account, BreezoMeter advises to stay within your API rate limits.
Checking your account rate limits can be done in your account settings page (opens new window)
# Max Range Limit
In order to optimize API request response times, BreezoMeter limits the maximum number of objects a request returns to 168. This is equivalent to an hours work of data for an entire week. To request data for more than a single week, BreezoMeter recommends you create multiple queries.
Requests which exceed the max range limit, return this HTTP 400 - Bad Request response:
# Error Responses
# HTTP Status Codes
BreezoMeter API uses conventional HTTP status codes in responses to indicate a request success or failure. Codes are organized into ranges. The first number of each range indicates the code type:
- 2xx: Success
- 4xx: Errors in the information provided by the request, such as a missing mandatory parameters, or data sent in an invalid/unrecognizable format
- 5xx: Server error
Here are the various HTTP status codes we might return:
| Code | Title | Description |
|---|---|---|
| 200 | OK | The request was successful |
| 400 | Bad request | The request did not include some or all of the expected parameters, or was incorrectly formatted |
| 403 | Forbidden | The request failed due to a permission issue. Check if you have the necessary permissions |
| 404 | Not found | The resource does not exist. Check URL |
| 408 | Request timeout | Connectivity issue occurred. Check your connection, or contact support if the problem persists |
| 500 | Internal server error | A problem with our servers. The developers were automatically notified. Try again later, or contact support for immediate assistance |
# Error Response Body
When an API request fails, the response JSON includes an object under the Error field, which provides detailed information that explains the problem.
The following example shows API’s HTTP 403 - Forbidden response to a missing API key (See, Authentication).
The Error object includes the following fields:
# Error Codes
The API provides the following error codes:
| Code | Description |
|---|---|
| missing_parameter | Required parameters missing from the request, and it cannot be completed |
| bad_request | Request parameters were inappropriate or included unexpected values |
| forbidden | Account lacks the relevant permissions to complete the request |
| location_unsupported | Information is unavailable for this location. Either BreezoMeter does not provide information for this country, or the request was in a maritime region |
| period_unsupported | Specified time period is longer than BreezoMeter currently support |
| range_limit | Request exceeded the 168 object maximum range limit |
| timeout_error | Unable to connect to BreezoMeter server due to poor connectivity or service outage |
| unknown_error | Unidentified server error. The developers were automatically notified. Try again later, or contact support for immediate assistance |
| data_unavailable | Data required by the server is unavailable. The developers were automatically notified. Try again later, or contact support for immediate assistance |
| api_key_not_provided | Request did not include an API Key |
| invalid_api_key | API Key is incorrect |
| key_disabled | API Key is disabled |
| user_disabled | Account is disabled. This may be because your plan has expired |
| daily_limit | Total number of objects queried has exceeded the account’s daily object quota of your evaluation plan |
# Versioning
Each of BreezoMeter APIs has a separate version number. The version of a specific API must be included in the endpoint request URL as shown below:
https://api.breezometer.com/air-quality/v2/current-conditions?...
This table shows the current version of each API:
| API | Version |
|---|---|
| Air Quality API | v2 |
| Pollen API | v1 |
| Weather API | v1 |
| Heatmap Tile Overlay API | v1 |
In cases where the release of a new API version causes compatibility issues for existing users, BreezoMeter will release updated API documentation and notify customers three months before the changes are made.
TIP
Note:
New integrations with BreezoMeter APIs should be developed with the latest version of each of the APIs. For further information on previous versions, please contact us .
# Customizing API Requests
You can customize API requests to only return the data you need for your software. This allows you to save bandwidth and decrease response time by requesting less information. You customize request by including the features parameter as part of the request, and set it up with the feature or list of features you wish to get back in the response.
TIP
Note:
Currently, customizing API requests is only available for the Air Quality API. To see the available features, refer to the features list, under the Air Quality API.
# Custom BAQI color palette
You can define and customize your BAQI color palette to correctly fit the returned colors to your background.
This should be done in scenarios where the returned colors do not fit your background correctly, or in cases where no colors are returned (e.g the traffic pollution vector tiles).
Our current color palettes include the following options:
red_green
indiper - Our new indiper color palette, which may be used for the heatmap.
indiper_dark - Our new indiper color palette, adapted for dark color backgrounds
indiper_light - Our new indiper color palette, adapted for light color backgrounds
For help creating a customized color palette, please contact our support team.
# Metadata
Each response returned by requests to Air Quality, Pollen, and Weather data API endpoints includes a metadata object. This object contains the details of the original request. Unless specified in the request, this field returns null . The metadata object was designed to simplify the process of evaluating and integrating BreezoMeter APIs. To return metadata, you include the metadata parameter in the request, and set it to true.
Get API Key
Talk to an expert