Weather stations

How to connect your weather station to OpenWeatherMap

We are glad to announce our new API version for managing your personal weather stations - Weather Stations API 3.0 (beta). It went through some essential changes in comparison with the previous version.

The biggest improvement is that users have more flexibility of their stations, and can share/transfer data related to them. The new RESTful style eases this process. In the previous version, a user account was limited to a single station, but with the new version, users can add as many stations as they need.

The second innovation is an extended set of parameters which you can pass in the measurements. The data transfer protocol based on METAR and CWOP networks. You could learn more about it here.

We are launching the new API version in two stages. As for now you have the possibility to add and set up your meteorological stations using Weather Stations API 3.0 methods for stations management and measurements transmissions. In the nearest future we are planning to provide additional methods which will allow you to collect data from your stations for any period of time. Also we will add support for obtaining the aggregated information with various intervals (minute/hour/day). It'll be possible to receive aggregated history of measurements from your meteorological station for several years by a single query.

Three simple steps to connect your station to Weather Station API 3.0:

  1. Create an account in members area and receive a key to access API methods
  2. Register your station in our system using the new API version and get a unique identifier for the station.
  3. Transfer weather data using special API method. Note that now you may have several stations attached to your account, so it's important to pass the unique station identifier in every query.

Basic methods to retrieve data from station

These are two methods necessary to start working with OpenWeatherMap service: creation of the station and measurements transfer. Access to full list of API methods requires you to pass your personal key in the query.

When calling methods PUT and POST it's necessary to specify the header Content-Type: application/json

[POST] /stations

This method is used to register a station in the OpenWeatherMap service. You need to pass a set of parameters: external identifier, station name and its geographical arrangement. In case of successful creation method returns an HTTP code 201.

URL example

http://api.openweathermap.org/data/3.0/stations

Request parameters

{
  "external_id": "SF_TEST001",
  "name": "San Francisco Test Station",
  "latitude": 37.76,
  "longitude": -122.43,
  "altitude": 150
}

Headers

Content-Type: application/json

API Response

{
  "ID": "583436dd9643a9000196b8d6",
  "updated_at": "2016-11-22T12:15:25.96727176Z",
  "created_at": "2016-11-22T12:15:25.967271732Z",
  "user_id": "557066d0ff7a7e3897531d94",
  "external_id": "SF_TEST001",
  "name": "San Francisco Test Station",
  "latitude": 37.76,
  "longitude": -122.43,
  "altitude": 150,
  "source_type": 5
}

[POST] /measurements

This method is used to transfer measurements collected from your station. Full description of possible data structures is provided below. Measurements are transferred in an array which allows to specify several data sets at once and to perform a postponed sending. In case of successful measurements dispatch method returns an HTTP code 204.

URL example

http://api.openweathermap.org/data/3.0/measurements

Request parameters

[
  {
    "station_id": "583436dd9643a9000196b8d6",
    "dt": 1479817340,
    "temperature": 18.7,
    "wind_speed": 1.2,
    "wind_gust": 3.4,
    "pressure": 1021,
    "humidity": 87,
    "rain_1h": 2,
    "clouds": [
      {
          "condition": "NSC"
      }
    ]
  }
]

Headers

Content-Type: application/json

API Response

[
  {
    "type": "m",
    "date": 1480508280,
    "station_id": "583d7bbbebb3ff000123f1ce",
    "temp": {
        "max": 22.7,
        "min": 21.7,
        "average": 22.03,
        "weight": 3
    },
    "humidity": {
        "average": 76.33,
        "weight": 3
    },
    "wind": {
        "deg": 160,
        "speed": 3.3
    },
    "pressure": {
        "min": 1031,
        "max": 1033,
        "average": 1031.67,
        "weight": 3
    },
    "precipitation": {}
  },
  {
    "type": "m",
    "date": 1480599660,
    "station_id": "583d7bbbebb3ff000123f1ce",
    "temp": {
        "max": 21.7,
        "min": 21.7,
        "average": 21.7,
        "weight": 1
    },
    "humidity": {
        "average": 77,
        "weight": 1
    },
    "wind": {},
    "pressure": {
        "min": 1031,
        "max": 1031,
        "average": 1031,
        "weight": 1
    },
    "precipitation": {}
  }
]

Parameter

Type & Units

Description

station_id

The internal ID of the station which is generated during creation

dt

Unix Timestamp

Time of measurement

temperature

Celsius

The air temperature

wind_speed

m/s

Wind speed

wind_gust

m/s

Maximum speed of wind gusts

wind_deg

Degrees from 0 to 360

Wind direction

pressure

Hectopascal

Atmospheric pressure

humidity

%

Relative air humidity

rain_1h

mm

Rainfall in the last hour

rain_6h

mm

Rainfall in the last 6 hours

rain_24h

mm

Rainfall for the last days

snow_1h

mm

Snow in the last hour

snow_6h

mm

Snow in the last 6 hours

snow_24h

mm

Snow for the last days

dew_point

Celsius

Dew point

humidex

Celsius

Index of temperature and humidity

heat_index

Celsius

Heat index

visibility_distance

km

Distance of direct visibility, METAR

visibility_prefix

N, E, S, W

Prefix at distinctions of visibility in the directions, METAR

clouds[]:distance

m

Height of the lower bound of overcast, METAR

clouds[]:condition

SKC, NSC, FEW, SCT, BKN, OVC

Cloud amount, METAR

clouds[]:cumulus

CB, TCU

Convective overcast, METAR

weather[]:precipitation

Additional description, METAR

weather[]:descriptor

Additional description, METAR

weather[]:intensity

Additional description, METAR

weather[]:proximity

Additional description, METAR

weather[]:obscuration

Additional description, METAR

weather[]:other

Additional description, METAR

[GET] /measurements

This method is used for receiving aggregated measurements from stations. In total, there are 3 supported unit types - minutes, hours, and days. Thus, there is a possibility to query the station’s historical measurements for any time interval with the desired level of detail.

At the moment the aggregation uses the fixed list of parameters from the collection of measurements - temperature, humidity, pressure, speed and wind direction, precipitation. In the future this list will extend.

The following parameters are mandatory in the request - an interval of measurements, the internal identifier of the station, type of the unit and the maximum number of records which can be returned. They are transferred in a line of GET-request as parameters.

URL Example

http://api.openweathermap.org/data/3.0/measurements?station_id=...&type=...&limit=...

URL Example

[
{
  "type": "m",
  "date": 1480508280,
  "station_id": "583d7bbbebb3ff000123f1ce",
  "temp": {
      "max": 22.7,
      "min": 21.7,
      "average": 22.03,
      "weight": 3
  },
  "humidity": {
      "average": 76.33,
      "weight": 3
  },
  "wind": {
      "deg": 160,
      "speed": 3.3
  },
  "pressure": {
      "min": 1031,
      "max": 1033,
      "average": 1031.67,
      "weight": 3
  },
  "precipitation": {}
},
{
  "type": "m",
  "date": 1480599660,
  "station_id": "583d7bbbebb3ff000123f1ce",
  "temp": {
      "max": 21.7,
      "min": 21.7,
      "average": 21.7,
      "weight": 1
  },
  "humidity": {
      "average": 77,
      "weight": 1
  },
  "wind": {},
  "pressure": {
      "min": 1031,
      "max": 1031,
      "average": 1031,
      "weight": 1
  },
  "precipitation": {}
}
]

Parameter

Description

Example

station_id

The internal ID of the station which you got during her creation

583d7bbbebb3ff000123f1ce

type

Type of the aggregated data - minute, hour or day. Specifies the letters m, h or d respectively

m

limit

The maximum number of records with the aggregated measurements which can return in the answer

100

from

The beginning of an interval on which data are requested. Is specified in Unix Timestamp format

1480300000

to

The end of an interval on which data are requested. Is specified in Unix Timestamp format

1480700000

Additional features of Weather Stations API 3.0

List all stations, show information about one station, change and remove stations attached to your account.

[GET] /stations

This method is used to obtain the list of all stations added to your account with a standard set of attributes: external and internal identifiers, creation and update timestamps, name, geographical arrangement, height above sea level and station rank.

http://api.openweathermap.org/data/3.0/stations
[
  {
    "id": "583436dd9643a9000196b8d6",
    "created_at": "2016-11-22T12:15:25.967Z",
    "updated_at": "2016-11-22T12:15:25.967Z",
    "external_id": "SF_TEST001",
    "name": "San Francisco Test Station",
    "longitude": -122.43,
    "latitude": 37.76,
    "altitude": 150,
    "rank": 0
  },
  {
    "id": "5834367b9643a9000196b8d5",
    "created_at": "2016-11-22T12:13:47.135Z",
    "updated_at": "2016-11-22T12:13:47.135Z",
    "external_id": "NY_TEST001",
    "name": "New York Test Station",
    "longitude":-73.99,
    "latitude": 40.72,
    "altitude": 30,
    "rank": 0
  }
]

[GET] /stations/{:id}

This method is used to get information about one station with a standard set of attributes: external and internal identifiers, creation and update timestamps, name, geographical arrangement, height above sea level and station rank.

http://api.openweathermap.org/data/3.0/stations/583436dd9643a9000196b8d6
{
  "id": "583436dd9643a9000196b8d6",
  "created_at": "2016-11-22T12:15:25.967Z",
  "updated_at": "2016-11-22T12:15:25.967Z",
  "external_id": "SF_TEST001",
  "name": "San Francisco Test Station",
  "longitude": -122.43,
  "latitude": 37.76,
  "altitude": 150,
  "rank": 0
}

[PUT] /stations/{:id}

This method is used to change information about the station. Parameters available for modification: external identifier, name, geographical arrangement, height above sea level. In case of successful change method returns an HTTP code 200.

URL Example

http://api.openweathermap.org/data/3.0/stations/583436dd9643a9000196b8d6

Request parameters

{
  "external_id": "SF_UPD001",
  "name": "San Francisco Updated Station",
  "latitude": 37.80,
  "longitude": -122.47,
  "altitude": 143
}

Headers

Content-Type: application/json

API Response

{
  "id": "583436dd9643a9000196b8d6",
  "created_at": "2016-11-22T12:15:25.967Z",
  "updated_at": "2016-11-22T12:44:20.170544353Z",
  "external_id": "SF_UPD001",
  "name": "San Francisco Updated Station",
  "longitude": -122.47,
  "latitude": 37.8,
  "altitude": 143,
  "rank": 0
}

[DELETE] /stations/{:id}

This method is used to remove a station from your account. In case of successful removal method returns an HTTP code 204 (Successful answer). Be careful: after this operation all measurements received from the removed station are deleted permanently, so they couldn't be restored.

URL Example

http://api.openweathermap.org/data/3.0/stations/583436dd9643a9000196b8d6

URL Example

{
   "id": "583436dd9643a9000196b8d6",
   "created_at": "2016-11-22T12:15:25.967Z",
   "updated_at": "2016-11-22T12:15:25.967Z",
   "external_id": "SF_TEST001",
   "name": "San Francisco Test Station",
   "longitude": -122.43,
   "latitude": 37.76,
   "altitude": 150,
   "rank": 0
}

Possible errors:

In case of an error you will receive six-digit HTTP codes:

Parameters

400 000

Error in input data

500 000

Internal error

404 000

Object not found

With the following structure:

Possible errors:

{
  "code": 000000,
  "message": "string"
}
  • code Six-digit error code. First three digits stands for an HTTP code, second - for a special error code.
  • message Error description