This page provides documentation for our climate APIs. There are currently four APIs: data, records, normals, and metadata. Each API returns a specific type of data.
- Climate data: The climate data API simply returns historical climate data for the specified location. The data comes at either hourly, daily, or monthly intervals as specified in the query. This API is used to find out what weather conditions were like on a certain day or range of days. It just returns past weather observations, which can then be further analyzed as needed.
- Climate records: The climate records API returns record values at a specified location at a specified time. For example, if you want to know what the highest ever temperature recorded on January 15 was in a given city, you would use the records API. This API allows you to quickly identify record values without having to search through all the data yourself. While max/min records are most common, the api can also return the earliest or latest dates of a given weather condition, consecutive days with a given weather condition, or the most or least number of occurences of a given weather condition.
- Climate normals: The climate normals API returns normal values for a specified location. The normals API can return daily, monthly, or yearly normals, for any range of years. Typically, normals are calculated for a 30-year period. We currently use the 1981-2010 period to calculate 'normal' climatological values, but this will soon change to use 1991-2020 normals. For some applications it may be more desireable to calculate normals using a custom range. With the normals API, you can calculate normals for any time range that you need. The normals API can answer questions like 'What is the normal high temperature in April' or 'What is the normal dewpoint on August 17'.
- Climate metadata: The climate metadata API returns data about available locations in the database. Users can either search for locations by point or bounding box. If a point is specified, then a radius is given to return all stations within the given radius from the point. If a bounding box is specified, all stations within the box are returned. These searches allow users to quickly identify locations within the area of interest. There is no cost to using the metadata API, but you must have an API key to gain access.
To learn more about how to use these APIs, continue to the 'Getting Started' section below.
There are two main ways that our APIs can be used: programmatically or with an API client. Developers can use the APIs programmatically within their own apps or projects to access Canadian climate data. Non-developers or non-technical users can utilize an API client to query the APIs. Some examples of API clients are listed below (Weatherlogics does not specifically endorse any of these third-party API clients):Postman Client. Talend API Tester. Chrome plugin required. Insomnia Client.
Create an API Key
To use the Weatherlogics climate APIs you will require an API key. Getting a key is simple, just create an account on this website and generate one!
- Click the icon in the far top-right corner of the screen to reveal the user login sidebar.
- Click 'Sign Up Here' and then fill out the form to create your account.
- Login with your new account and click your name in the top-right corner to reveal the sidebar again.
- Click 'API Token' on the sidebar menu.
- On the API Token page, click the generate token button to create your API token. You will need to enter your credit card information in order to generate an api key.
- If you navigate back to the API Token page, you will see your api key. You can start using it!
Once you have your api key, be sure to store it in a safe place. The API key connects your queries to your account and is used for billing. If your API key is not stored securely, it could be used by others to incur charges on your account.
Using your API Key
To use your API key, it must be passed through the request header. If you are using an API client, there will be a place to enter headers. Simply set the header (key) to x-api-key and use your API key as the value. If you are using your API key programatically, you will also use x-api-key as the header and your API key as the value. The syntax for actually making the request will vary based on the programming language that you are using. Click here for an example of how to add a header in Postman.
Metering and Billing
All users are given 500 free credits per month when using each API. After your free credits have been used, you will start being billed for API usage. You can monitor your API usage by logging into your account. For more information about billing, visit the pricing page