# Introduction

Last updated: Nov 1, 2018

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

Last updated: Nov 1, 2018

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

Last updated: Nov 1, 2018

# 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

Last updated: Nov 1, 2018

# Data APIs

This example shows the structure of the JSON object that the Air Quality, Pollen, and Weather APIs return:

  -   {         "metadata" null ,           "data" {  ...  } ,         "error" null       }  

Each object contains the following fields:

metadata
object
An object that contains the meta information of the original request. Unless specified in the request, this field returns null.

For more information, see Metadata section.
data
object
An object that contains the relevant data for successful requests.
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.
error
object
An object that describes why a request failed.
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 ,           "data" {  ...  } ,         "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 ,     -     "data" [             {  ...  } ,             {  ...  } ,             {  ...  }         ] ,        "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

Last updated: Nov 1, 2018

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:

  -   {         "metadata" null ,         "data" null ,     -     "error" {           "code" "api_key_not_provided" ,           "title" "API key not provided" ,           "detail" "User did not provide API key"         }       }  

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

Last updated: Nov 1, 2018

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

Last updated: Nov 1, 2018

# 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

Last updated: Nov 1, 2018

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

Last updated: Nov 1, 2018

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

Last updated: Nov 1, 2018

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:

  -   {         "metadata" null ,         "data" null ,     -     "error" {           "code" "range_limit" ,           "title" "Requested Time Period Exceeds the Range Limit" ,           "detail" "The time period specified in the request exceeds the maximum range limit of 168 hours. Make sure you've specified the 'hours' parameter within the maximum range limits of 168 hours"         }       }  

# Error Responses

Last updated: Nov 1, 2018

# HTTP Status Codes

Last updated: Nov 1, 2018

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

Last updated: Nov 1, 2018

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).

  -   {         "metadata" null ,         "data" null ,     -     "error" {           "code" "api_key_not_provided" ,           "title" "API key not provided" ,           "detail" "User did not provide API key"         }       }  

The Error object includes the following fields:

code
object
A parseable short code that identifies the error. See Error Codes for the complete list of error code.
title
object
A human-readable text that indicates the reason why the request failed.
detail
object
A human-readable text that provides full description of the error’s cause, and how to fix it.

# Error Codes

Last updated: Nov 1, 2018

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

Last updated: Nov 1, 2018

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

Last updated: Nov 1, 2018

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 red green

  • indiper - Our new indiper color palette, which may be used for the heatmap. indiper

  • indiper_dark - Our new indiper color palette, adapted for dark color backgrounds indiper dark

  • indiper_light - Our new indiper color palette, adapted for light color backgrounds indiper light

For help creating a customized color palette, please contact our support team.

# Metadata

Last updated: Nov 1, 2018

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.

Integrate BreezoMeter's data in your products today