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 main improvement is that users now have more flexible control of their stations and allowed to share and transfer data related to them. New API in RESTful style makes this process easy and convenient. In the previous version user's account was limited to single station, but with our new version users are allowed to 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 the aggregated measurements from the station. In total are supported 3 types of units - minute, hour and day. Thus, there is possible to query history of measurements from the station for any interval of time with the necessary specification.

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=... 
                    
[
{
  "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.

URL Example

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 
                    
{
   "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:

400 000 Error in input data
500 000 Internal error
404 000 Object not found

With the following structure:


{
  "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
We use cookies to personalize content and to analyze our traffic. Please decide if you are willing to accept cookies from our website.
Advanced Settings