Ambee's APIs deliver hyperlocal and highly accurate climate data directly to your applications. Organized around REST, these APIs return HTTP response codes, with responses encoded in JSON.
To begin using Ambee's APIs, you'll need an active Ambee account to generate your custom API keys. These keys grant access to our diverse datasets. For detailed instructions on creating an Ambee account and generating access keys, please refer to our Authentication section.
You can also review our API endpoints for a complete overview of the datasets we offer.
Start here
Get valuable climate insights now
API endpoints are specific URLs provided by the Ambee API for performing various operations, primarily retrieving resources. Each endpoint corresponds to a specific function and is accessed using standard HTTP methods, predominantly GET, but also POST, where applicable.
Ambee offers 37 unique climate-centric endpoints to provide granular information across various datasets.
End Point | Data type | duration | region |
---|---|---|---|
Air Quality | |||
/latest/by-lat-lng Geospatial search | Latest Updates hourly | Current hour 1 h interval | Global |
/latest/by-city Citywise search | Latest Updates hourly | Current hour 1 h interval | Global |
/latest/by-country-code Countrywise search | Latest Updates hourly | Current hour 1 h interval | Global |
/latest/by-postal-code Postal search | Latest Updates hourly | Current hour 1 h interval | Global |
/history/by-lat-lng Geospatial search | History | 48 hours 1 h interval | Global |
/history/by-postal-code Postal search | History | 48 hours 1 h interval | Global |
/forecast/aq/by-lat-lng Geospatial search | Forecast Updates in 12 hrs | 48 hours 1 h interval | US |
Pollen | |||
/latest/pollen/by-lat-lng Geospatial search | Latest Updates hourly | Current hour 1 h interval | Global (except South America, Arctic, Antarctica and any ocean) |
/latest/pollen/by-place Placewise search | Latest Updates hourly | Current hour 1 h interval | Global (except South America, Arctic, Antarctica and any ocean) |
/history/pollen/by-lat-lng Geospatial search | History | 48 hours 1 h interval | Global (except South America, Arctic, Antarctica and any ocean) |
/history/pollen/by-place Placewise search | History | 48 hours 1 h interval | Global (except South America, Arctic, Antarctica and any ocean) |
/forecast/pollen/by-lat-lng Geospatial search | Forecast Updates hourly | 48 hours 1 h interval | Global (except South America, Arctic, Antarctica and any ocean) |
Placewise search | Forecast Updates hourly | 48 hours 1 h interval | Global (except South America, Arctic, Antarctica and any ocean) |
/forecast/v2/pollen/120hr/by-lat-lng Geospatial search | Forecast Updates hourly | 120 hours 3 h interval | Global (except South America, Arctic, Antarctica and any ocean) |
/forecast/v2/pollen/120hr/by-place Placewise search | Forecast Updates hourly | 120 hours 3 h interval | Global (except South America, Arctic, Antarctica and any ocean) |
Weather | |||
/weather/latest/by-lat-lng Geospatial search | Latest Updates hourly | Current hour 1 h interval | Global (except Arctic, Antarctica and oceans) |
/weather/history/by-lat-lng Geospatial search | History | 48 hours 1 h interval | Global (except Arctic, Antarctica and oceans) |
/weather/forecast/by-lat-lng Geospatial search | Forecast Updates daily | 48 hours 1 h interval | Global (except Arctic, Antarctica and oceans) |
Wildfire | |||
/fire/latest/by-lat-lng Geospatial search | Latest Updates hourly | Last 7 days | Global |
/fire/latest/by-place Placewise search | Latest Updates hourly | Last 7 days | Global |
Natural Disaster | |||
/disasters/latest/by-lat-lng Geospatial search | Latest Updates in 12 hrs | Last 1 month | Global |
/disasters/latest/by-country-code Countrywise search | Latest Updates in 12 hrs | Last 1 month | Global |
/disasters/by-eventId Eventwise search | Latest Updates in 12 hrs | Last 1 month | Global |
/disasters/latest/by-continent Continentwise search | Latest Updates in 12 hrs | Last 1 month | Global |
/disasters/history/by-lat-lng Geospatial search | History | Last 1 month | Global |
/disasters/history/by-country-code Countrywise search | History | Last 1 month | Global |
/disasters/history Historywise search | History | Last 1 month | Global |
/disasters/history/by-continent Continentwise search | History | Last 1 month | Global |
Location Services | |||
/geocode/reverse/by-lat-lng Geospatial search | Latest | N/A | Global |
/geocode/by-place Placewise search | Latest | N/A | Global |
Elevation | |||
/elevation/latest/by-lat-lng Geospatial search | Latest Updates in 6 months | N/A | North America |
/elevation/latest/by-place Placewise search | Latest Updates in 6 months | N/A | North America |
Influenza-like Illness [Beta] | |||
/ili/forecast/by-lat-lng Geospatial search | Forecast Updates daily | 30 days 3 day interval | United states & Germany (except Hawai & small islands) |
To access Ambee endpoints, you must authenticate your requests using an API Key. For more information on API keys, please refer to the API Keys section.
You can signup and get your API Key from the Ambee API Dashboard.
1. Go to the API Dashboard to sign up using your Google or business account credentials.
2. After signing up, your API key will be displayed on the dashboard. Copy this key and start using it in your API requests.
Ambee products are protected from unauthorized use by requiring proper authentication credentials for API calls. These credentials consist of an API key, a unique alphanumeric string linking your Ambee account to the specific API. Users subscribed to the enterprise plan are able to generate multiple API keys.
A default "private" API key is available for use on your Ambee API dashboard . You can reset the API key every 30 days in the API dashboard using your registered email address.
This key allows access to all your resources via various endpoints and includes:
For more information on how to create API keys, refer to the authentication section.
After generating the API key, it is absolutely essential to keep it secure. Each key uniquely identifies and grants access to your Ambee account, allowing anyone with the key to use it without your knowledge.
If you suspect that your key has been compromised, either regenerate the API key or contact Ambee support immediately.
To send an authenticated API request, include the API key as a part of the request headers. Ensure you include a valid API key to access the API and make a call.
Requests without an API key or with an invalid API key will receive an HTTP 401 - Invalid Authentication Key.
{
"error": {
"code": 401,
"message": "Invalid Authentication Key."
}
}
When using the Ambee API, you might encounter various status codes indicating issues with your requests. Understanding these codes can help you troubleshoot and resolve problems effectively. Below is a table of common status codes, their descriptions, and potential solutions.
http code | text | description | resolution |
---|---|---|---|
200 | Ok | Everything worked as expected. | No action is needed. |
206 | Partial data | You have exhausted your API limit. This response is trimmed from the original output, with only the data count pending from your API plan. | Check your API usage and upgrade your plan if necessary. Consider optimizing your requests to reduce usage. |
299 | Deprecated | The current version of the API doesn't support this functionality. | Refer to the latest API documentation and update your implementation to use supported functionalities. |
400 | Bad request | The request was unacceptable. This can happen due to invalid parameters, missing required fields, or incorrect data formats. | Ensure that your request is properly formatted, includes all required parameters, and that all data types are correct. Refer to the API documentation for the correct request structure. |
401 | Unauthorized | No valid API key provided. | Verify that you have included a valid API key in your request header. Ensure your API key is active and has the necessary permissions. |
403 | Forbidden | The API key doesn't have the permissions. | Check the permissions associated with your API key. Ensure that your API key is authorized to access the endpoint you are trying to reach. |
404 | Not Found | The requested resource doesn't exist. | Verify the endpoint URL and the resource ID to ensure they are correct. Refer to the API documentation to confirm the correct paths and identifiers. |
422 | Quota exceeded | The user has reached the allowed limit or quota allocated for their plan. | Monitor your API usage and consider upgrading your plan if you frequently exceed your quota. Implement efficient data retrieval strategies to stay within limits. |
429 | Rate limit | The user has reached the allowed limit or quota allocated for their plan. | Reduce the frequency of your requests or upgrade your plan to a higher rate limit. Implement exponential backoff in your retry logic to handle rate limits gracefully. |
500 | Internal Server Error | Something went wrong on our end. | Retry the request later or contact Ambee support if the issue persists. Monitor the status page for any ongoing incidents. |
By understanding these codes and following the suggested resolutions, you can ensure smooth and efficient interaction with the Ambee API. For further assistance, refer to the detailed API documentation or contact our support team.
Ambee's API responses support multiple languages, enabling you to customize the language of responses to better suit your needs. By default, responses are provided in English, but you can specify a different language by using the ‘Accept-Language’ header in your API requests.
Accept_Language
Accept-Language: LANGUAGE_CODE
language | code |
---|---|
German | DE |
Spanish | ES |
French | FR |
Japanese | JA |
Dutch | NL |
Italian | IT |
Chinese | CN |
English | EN |
Accept-Language: ES
Next
Playground
Yes
No