Live API

The Live API provides access to the latest measurements from one station or all stations.

License

To use data from Pioupiou stations, you must comply with the license available on the Data Licensing page.

Endpoints

# latest measurements only
GET http://api.pioupiou.fr/v1/live/{station_id}
# latest measurements with complete metadata
GET http://api.pioupiou.fr/v1/live-with-meta/{station_id}

Arguments

# for a single station
{station_id} : Numeric ID of the station
# for all stations
{station_id} : "all"

Responses

The Live API provides JSON responses.

Response examples

Single station, latest measurements only

$ curl "http://api.pioupiou.fr/v1/live/110"
{
  "doc": "http://developers.pioupiou.fr/api/live/",
  "license": "http://developers.pioupiou.fr/data-licensing",
  "attribution": "(c) contributors of the Pioupiou wind network <http://pioupiou.fr>",
  "data": {
    "id": 110,
    "meta": {
      "name": "Pioupiou 110"
    },
    "location": {
      "latitude": 51.368464,
      "longitude": 3.458852,
      "date": "2015-08-16T14:26:01.000Z",
      "success": true
    },
    "measurements": {
      "date": "2015-08-17T22:07:27.000Z",
      "pressure": null,
      "wind_heading": 292.5,
      "wind_speed_avg": 14,
      "wind_speed_max": 22.5,
      "wind_speed_min": 7
    },
    "status": {
      "date": "2015-08-17T22:07:27.000Z",
      "snr": 23.03,
      "state": "on"
    }
  }
}

Single station, latest measurements with complete metadata

$ curl "http://api.pioupiou.fr/v1/live-with-meta/110"
{
  "doc": "http://developers.pioupiou.fr/api/live/",
  "license": "http://developers.pioupiou.fr/data-licensing",
  "attribution": "(c) contributors of the Pioupiou wind network <http://pioupiou.fr>",
  "data": {
    "id": 110,
    "meta": {
      "name": "Pioupiou 110",
      "description": null,
      "picture": null,
      "date": null,
      "rating": {
        "upvotes": 0,
        "downvotes": 0
      }
    },
    "location": {
      "latitude": 51.368464,
      "longitude": 3.458852,
      "date": "2015-08-16T14:26:01.000Z",
      "success": true
    },
    "measurements": {
      "date": "2015-08-17T22:19:31.000Z",
      "pressure": null,
      "wind_heading": 292.5,
      "wind_speed_avg": 12,
      "wind_speed_max": 21,
      "wind_speed_min": 6.5
    },
    "status": {
      "date": "2015-08-17T22:19:31.000Z",
      "snr": 23.01,
      "state": "on"
    }
  }
}

All stations, latest measurements only

$ curl "http://api.pioupiou.fr/v1/live/all"
{
  "doc": "http://developers.pioupiou.fr/api/live/",
  "license": "http://developers.pioupiou.fr/data-licensing",
  "attribution": "(c) contributors of the Pioupiou wind network <http://pioupiou.fr>",
  "data": [
    {
      "id": 1,
      "meta": {
        "name": "Pioupiou 1",
      },
      "location": {
        "latitude": 0,
        "longitude": 0,
        "date": null,
        "success": false
      },
      "measurements": {
        "date": "2015-08-18T08:19:46.000Z",
        "pressure": null,
        "wind_heading": 157.5,
        "wind_speed_avg": 2,
        "wind_speed_max": 4,
        "wind_speed_min": 0
      },
      "status": {
        "date": "2015-08-18T08:19:46.000Z",
        "snr": 23.24,
        "state": "on"
      }
    },
    {
      "id": 27,
      "meta": {
        "name": "Pioupiou 27",
      },
      "location": {
        "latitude": 44.907284,
        "longitude": 5.677965,
        "date": "2015-08-15T13:48:38.000Z",
        "success": true
      },
      "measurements": {
        "date": "2015-08-18T08:18:26.000Z",
        "pressure": null,
        "wind_heading": 45,
        "wind_speed_avg": 15,
        "wind_speed_max": 17.5,
        "wind_speed_min": 10.5
      },
      "status": {
        "date": "2015-08-18T08:18:26.000Z",
        "snr": 12.01,
        "state": "on"
      }
    },
    {...more stations...},
    {...more stations...}
  ]
}

All stations, latest measurements with complete metadata

$ curl "http://api.pioupiou.fr/v1/live-with-meta/all"
{
  "doc": "http://developers.pioupiou.fr/api/live/",
  "license": "http://developers.pioupiou.fr/data-licensing",
  "attribution": "(c) contributors of the Pioupiou wind network <http://pioupiou.fr>",
  "data": [
    {
      "id": 1,
      "meta": {
        "name": "Pioupiou 1",
        "description": null,
        "picture": null,
        "date": null,
        "rating": {
          "upvotes": 0,
          "downvotes": 0
        }
      },
      "location": {
        "latitude": 0,
        "longitude": 0,
        "date": null,
        "success": false
      },
      "measurements": {
        "date": "2015-08-18T08:19:46.000Z",
        "pressure": null,
        "wind_heading": 157.5,
        "wind_speed_avg": 2,
        "wind_speed_max": 4,
        "wind_speed_min": 0
      },
      "status": {
        "date": "2015-08-18T08:19:46.000Z",
        "snr": 23.24,
        "state": "on"
      }
    },
    {
      "id": 27,
      "meta": {
        "name": "Pioupiou 27",
        "description": null,
        "picture": null,
        "date": null,
        "rating": {
          "upvotes": 0,
          "downvotes": 0
        }
      },
      "location": {
        "latitude": 44.907284,
        "longitude": 5.677965,
        "date": "2015-08-15T13:48:38.000Z",
        "success": true
      },
      "measurements": {
        "date": "2015-08-18T08:18:26.000Z",
        "pressure": null,
        "wind_heading": 45,
        "wind_speed_avg": 15,
        "wind_speed_max": 17.5,
        "wind_speed_min": 10.5
      },
      "status": {
        "date": "2015-08-18T08:18:26.000Z",
        "snr": 12.01,
        "state": "on"
      }
    },
    {...more stations...},
    {...more stations...}
  ]
}

Responses parameters details

A data object is returned. It contains a single station {} or an array of all stations[{},{}..{},{}].

Every station contains the following parameters :

Name live live-with-meta Description Unit
id x x Numeric ID of the station
meta.name x x Name of the station
meta.description x Description of the station, or null
meta.picture x URL of station's picture, or null
meta.date x Date of last metadata update, or null ISO 8601, UTC
meta.rating.upvotes x Station rating : Positive votes count
meta.rating.downvotes x Station rating : Negative votes count
location.latitude x x Last known Latitude of the station, or null WGS84
location.longitude x x Last known Longitude of the station, or null WGS84
location.date x x Date of last location update (succeed or failed), or null ISO 8601, UTC
location.success x x Is the last known position still valid ? true or false
measurements.date x x Date of last measurements, or null ISO 8601, UTC
measurements.pressure x x null (deprecated)
measurements.wind_heading x x Wind heading, or null (0° means the wind is blowing from North to Sud) degrees
measurements.wind_speed_avg x x Wind speed average, or null (over the last 4 minutes before measurements.date, divide by 1.852 for converting to knots) km/h
measurements.wind_speed_min x x Minimum wind speed, or null (over the last 4 minutes before measurements.date, divide by 1.852 for converting to knots) km/h
measurements.wind_speed_max x x Maximum wind speed, or null (over the last 4 minutes before measurements.date, divide by 1.852 for converting to knots) km/h
status.date x x Date of the last contact with the station, or null ISO 8601, UTC
status.snr x x Signal-to-Noise ratio = radio link quality, or null (<10 : bad, >20: very good) dB
status.state x x Station power state, "on", "off" or null. "off" means that the station have been shutdown by pressing it's power switch.

Error codes

An HTTP/1.1 200 OK header is sent on successful request. HTTP status code other than 200 means that an error has occured.

In most cases the application will return a JSON object, including details about the error.

$ curl -i "http://api.pioupiou.fr/v1/live/999999"
HTTP/1.1 404 Not Found

{
  "error_code": "station_not_found",
  "error_message": "unable to find station with this {station_id}"
}
error_code HTTP code description
station_not_found 404 The requested station is not in the database
missing_argument 400 The station ID is missing or invalid

Error detection:

For reliable error detection, your application must monitor the HTTP code instead of the JSON response.

JSONP and CORS

The API supports cross-origin requests.

Cross-Origin Resource Sharing

An Access-Control-Allow-Origin: * header is sent with all responses. It means that you can call the API directly from your javascript page.

JSONP

JSONP is also supported, even if its use is no longer encouraged.

The name of the callback function must be placed in query string callback argument:

$ curl -i "http://api.pioupiou.fr/v1/live/1?callback=myCallBackFunction"
HTTP/1.1 200 OK
Content-Type: text/javascript; charset=utf-8

/**/ typeof myCallBackFunction === 'function' && myCallBackFunction({
  "doc": "http://developers.pioupiou.fr/api/live/",
  "license": "http://pioupiou.fr/license/data",
  "attribution": "(c) contributors of the Pioupiou wind network <http://pioupiou.fr>",
  "data": {
    "id": 1,
    "meta": {
      "name": "Pioupiou 1"
    },
    "location": {
      "latitude": 0,
      "longitude": 0,
      "date": null,
      "success": false
    },
    "measurements": {
      "date": "2015-08-18T08:55:46.000Z",
      "pressure": null,
      "wind_heading": 157.5,
      "wind_speed_avg": 2,
      "wind_speed_max": 3,
      "wind_speed_min": 1
    },
    "status": {
      "date": "2015-08-18T08:55:46.000Z",
      "snr": 23.31,
      "state": "on"
    }
  }
});

Limitations

Updates for all stations or a single station should not be requested more often than every 60 seconds. If you need real-time information, please use the Push API.

If you use this API for a high-traffic application, you have to set-up your own cache server.