menu

Home

search

Ambee APIs

Introduction

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 free API key to start using our APIs. For detailed instructions on generating API keys, please refer to our authentication section.

Get valuable climate insights now

Try our APIs without code using Ambee’s interactive playground or Postman.

Endpoints

Edit Filters

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 PointData typedurationregion
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
Updates hourly
Current hour
1 h interval
Global
/history/by-lat-lng
Geospatial search
History
48 hours
1 h interval
Global
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
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
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
Updates hourly
120 hours
3 h interval
Global (except South America, Arctic, Antarctica and any ocean)
Forecast
Updates hourly
120 hours
3 h interval
Global (except South America, Arctic, Antarctica and any ocean)
Weather
Latest
Updates hourly
Current hour
1 h interval
Global (except Arctic, Antarctica and oceans)
History
48 hours
1 h interval
Global (except Arctic, Antarctica and oceans)
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
Latest
Updates in 12 hrs
Last 1 month
Global
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
History
Last 1 month
Global
History
Last 1 month
Global
/disasters/history
Historywise search
History
Last 1 month
Global
History
Last 1 month
Global
Location Services
Latest
N/A
Global
/geocode/by-place
Placewise search
Latest
N/A
Global
Elevation
Latest
Updates in 6 months
N/A
North America
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)

Authentication

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.

Creating an API key

1. Go to the API Dashboard to sign up using your Google or business account credentials.

image

2. After signing up, your API key will be displayed on the dashboard. Copy this key and start using it in your API requests.

image

Access API keys

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.

Obtaining your API key

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:

  • 1. Permissions
  • 2. Rate limits
  • 3. Daily quota
  • 4. API usage

For more information on how to create API keys, refer to the authentication section.

Security note

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.

Using your API key

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.

Handling errors

Requests without an API key or with an invalid API key will receive an HTTP 401 - Invalid Authentication Key.

ERROR RESPONSE SAMPLE
{ "error": { "code": 401, "message": "Invalid Authentication Key." } }

Error codes

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

Locale

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.

Headers

Accept_Language

string
optional
Specify your preferred language for API responses.
Allowed value:
LANGUAGE_CODE
Default value:
English
REQUEST
Accept-Language: LANGUAGE_CODE

Supported Languages (On Demand)

Ambee supports a range of languages to accommodate global users. The following table lists the supported languages and their corresponding codes.
languagecode
German
DE
Spanish
ES
French
FR
Japanese
JA
Dutch
NL
Italian
IT
Chinese
CN
English
EN
To request responses in Spanish, include the following header in your API request:
EXAMPLE
Accept-Language: ES

Was this page helpful?
happy-emoji

Yes

sad-emoji

No