This tutorial will walk you through what a first time user of the WeatherLink v2 API needs to do in order to start retrieving weather observation data. If you do not have your own WeatherLink weather station setup yet you can use the WeatherLink v2 API in demo mode.

Step 1 - Get Your API Key and API Secret

To retrieve your WeatherLink v2 API Key and API Secret you can go to WeatherLink.com and visit the Account page at https://www.weatherlink.com/account.

Once on the Account page you can click the Generate v2 Key button to create a new WeatherLink v2 API Key and API Secret.

The API Secret must be protected and should never be passed as a query parameter to the API.

If your API Secret is compromised it will allow others to access the API while pretending to be you. If this occurs please go back to the Account page and click the Generate v2 Key button again. This will delete the old API Secret and create a new API Secret. You will then need to update your code to use the new API Secret.

Please note that the API Key will not be changed and can not be deleted when generating a new API Secret.

Step 2 - Get Your Station ID

Before you can download weather observation data you need to know the Station ID of your weather station. Currently, the WeatherLink v2 API accepts 2 forms of Station ID:

  • A unique integer Station ID that can only be retrieved by making an API call to the /stations API endpoint.
  • A UUID which can be retrieved by making an API call to the /stations API endpoint or you can find it in your browser address bar when viewing the station in question on WeatherLink.com.

The Station ID is different from your station’s Device ID or DID. The FAQ page has some brief explanations on why it is different from the Device ID of the past that was used in older WeatherLink APIs.

The API Reference documents information on what parameters/headers are available with each API call the WeatherLink v2 API supports.

To make the API call to the /stations API endpoint you need to make an HTTP GET API call to the following URL and include a header named X-Api-Secret set to the value of your API Secret.

https://api.weatherlink.com/v2/stations?api-key={YOUR API KEY}

The JSON response for the API call will contain a list of all stations that are accessible by the API Key.

Here is a sample segment of the API response JSON showing what the Station ID will look like. This sample JSON omits many additional fields of infomation like product number, time zone, GPS coordinates, etc. because that information will be different for your weather station.

{
    "stations": [
        {
            "station_id": 96230,
            "station_id_uuid": "9722cfc3-a4ef-47b9-befb-72f52592d6ed",
            "station_name": "Home WeatherLink Live"
        }
    ]
}

Step 3 - Get Current Conditions Data

Continuing with the Station ID from before, you will now make an API call to retrieve current conditions weather observation data. This is done by making an API call to the /current/{station-id} API path where you will replace the {station-id} path parameter with the Station ID. Both integer and UUID versions of the Station ID are accepted.

You can check the API Reference for information on what parameters are available with each API call the WeatherLink v2 API supports.

To make the API call to the /current/{station-id} API endpoint you need to make an HTTP GET API call to the following URL and include a header named X-Api-Secret set to the value of your API Secret.

https://api.weatherlink.com/v2/current/{station-id}?api-key={YOUR API KEY}

The JSON response for the API call will contain current condition observation data for the specified Station ID, assuming you have permission to view the station via the WeatherLink v2 API. Please refer to the Data Permissions documentation about what level of data access is available for the different combinations of weather station types and WeatherLink service plans.

Information about what the weather observation data API response looks like is at API Response.

Step 4 - Get Historic Data

Please Note:

In order to retrieve historic data for a station your subscription level to that station must be either Pro or Pro+.

Continuing with the Station ID from before, you will now make an API call to retrieve historic weather observation data. This is done by making an API call to the /historic/{station-id} API path where you will replace the {station-id} path parameter with the Station ID.

When retrieving historic weather observation data you need to provide Unix timestamps for the start and end of the period of time you want to download data for. Please note the current size limit of periods of time per historic data API call is documented at Size Limits.

You can check the API Reference for information on what parameters are available with each API call the WeatherLink v2 API supports.

In this tutorial example we will query for historic data from the day 2019-07-01 in the America/Los_Angeles timezone. To do this you need to use the following parameters:

  • Unix timestamp 1561964400 for the start-timestamp parameter.
  • Unix timestamp 1562050800 for the end-timestamp parameter.

In WeatherLink, the timestamps on historic data records represents the end of the data record’s recording time interval. For example, if your station generates 1 historic data record (also known as Archive data record) per hour then the record with the timestamp of 7:00 AM represents the summary of data for the hour of time between 6:00 AM and 7:00 AM. Therefore, any historic data record with a timestamp of midnight is actually the last record of the previous day’s data and not the first record of the new day.

Keeping this in mind, the WeatherLink v2 API uses the start-timestamp and end-timestamp parameters to look for data records where timestamps fall into an interval that can be expressed as (start-timestamp, end-timestamp]. This is equivalent to looking for data records with a timestamp > start-timestamp and <= end-timestamp.

To make the API call to the /historic/{station-id} API endpoint you need to make an HTTP GET API call to the following URL and include a header named X-Api-Secret set to the value of your API Secret.

The final URL with parameters for our example scenario is:

https://api.weatherlink.com/v2/historic/{station-id}?api-key={YOUR API KEY}&start-timestamp=1561964400&end-timestamp=1562050800

The JSON response for the API call will contain historic weather observation data for the specified Station ID, assuming you have permission to view the station via the WeatherLink v2 API. Please refer to the Data Permissions documentation about what level of data access is available for the different combinations of weather station types and WeatherLink service plans.

Information about what the weather observation data API response looks like is at API Response.