Archive API

The Archive API provides access to historical measurements from one station.

A single request can retrieve data for up to 31 days.

Output format can be either JSON, csv or tab-separated text file.

License

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

Endpoint

GET http://api.pioupiou.fr/v1/archive/{station_id}?start={start}&stop={stop}&format={format}

Arguments

Name Description
{station_id} Numeric ID of the station (Required)
{start} Start date (see below) or "last-hour" or "last-day" or "last-week" or "last-month" (Required)
{stop} Stop date (see below) or "now" (Required)
{format} Output format : "json" (default) or "csv" or "txt" (Optionnal)

Dates format

Dates and times are specified using the ISO 8601 format. The default timezone is UTC.

The full representation uses the following format:

yyyy-MM-ddTHH:mm:ss.SSSZ

The following table shows examples of valid dates and times:

Sample Description
2015 Amounts to 2015-01-01T00:00:00.000Z
2015-08 Amounts to 2015-08-01T00:00:00.000Z
2015-08-23 Amounts to 2015-08-23T00:00:00.000Z
2015-08-23T18 Amounts to 2015-08-23T18:00:00.000Z
2015-08-23T18:45 Amounts to 2015-08-23T18:45:00.000Z
2015-08-23T18:45Z Amounts to 2015-08-23T18:45:00.000Z (UTC)
2015-08-23T18:45+0200 Amounts to 2015-08-23T18:45:00.000+0200 (Paris, CET − Summer DST)
2015-01-01T18:45+0100 Amounts to 2015-01-01T18:45:00.000+0100 (Paris, CET − Winter DST)

To avoid errors, we recommend to always use UTC dates and times.

You can directly use date from Javascript's new Date().toISOString() or PHP's date("c").

Responses

The Live API provides JSON responses.

Response examples

May 2015, JSON

$ curl "http://api.pioupiou.fr/v1/archive/1?start=2015-05&stop=2015-06"
{
  "doc": "http://developers.pioupiou.fr/api/archive/",
  "license": "http://developers.pioupiou.fr/data-licensing",
  "attribution": "(c) contributors of the Pioupiou wind network <http://pioupiou.fr>",
  "legend": ["time","latitude","longitude","wind_speed_min","wind_speed_avg","wind_speed_max","wind_heading","pressure"],
  "units": ["utc","degrees","degrees","km/h","km/h","km/h","degrees","(deprecated)"],
  "data": [
    ["2015-05-01T00:03:54.000Z",45.30314,5.906867,3,4,5,45,null],
    ["2015-05-01T00:07:54.000Z",45.30314,5.906867,1,2,4,67.5,null],
    ["2015-05-01T00:11:54.000Z",45.30314,5.906867,0,0,0,67.5,null],
    ["2015-05-01T00:15:54.000Z",45.30314,5.906867,0,0,1,67.5,null],
    ["2015-05-01T00:19:54.000Z",45.30314,5.906867,0,0,0,0,null],
    ["2015-05-01T00:23:54.000Z",45.30314,5.906867,0,1,4,67.5,null],
    ...,
    ["2015-05-31T23:37:03.000Z",45.30314,5.906867,1,2,2,90,null],
    ["2015-05-31T23:41:03.000Z",45.30314,5.906867,0,0,1,90,null],
    ["2015-05-31T23:45:03.000Z",45.30314,5.906867,0,1,2,90,null],
    ["2015-05-31T23:49:03.000Z",45.30314,5.906867,0,0,1,90,null],
    ["2015-05-31T23:53:03.000Z",45.30314,5.906867,0,0,0,90,null],
    ["2015-05-31T23:57:03.000Z",45.30314,5.906867,0,0,0,0,null]
  ]
}

Last hour, JSON

$ curl "http://api.pioupiou.fr/v1/archive/110?start=last-hour&stop=now"
{
  "doc": "http://developers.pioupiou.fr/api/archive/",
  "license": "http://developers.pioupiou.fr/data-licensing",
  "attribution": "(c) contributors of the Pioupiou wind network <http://pioupiou.fr>",
  "legend": ["time","latitude","longitude","wind_speed_min","wind_speed_avg","wind_speed_max","wind_heading","pressure"],
  "units": ["utc","degrees","degrees","km/h","km/h","km/h","degrees","(deprecated)"],
  "data": [
    ["2015-08-18T12:48:23.000Z",51.368464,3.458852,1,10,17.5,247.5,null],
    ["2015-08-18T12:52:27.000Z",51.368464,3.458852,1,10.5,21,247.5,null],
    ["2015-08-18T12:56:27.000Z",51.368464,3.458852,7,15,26,247.5,null],
    ["2015-08-18T13:00:27.000Z",51.368464,3.458852,9.75,18.5,27,247.5,null],
    ["2015-08-18T13:04:33.000Z",51.368464,3.458852,8,17.5,27,247.5,null],
    ["2015-08-18T13:08:33.000Z",51.368464,3.458852,8.25,14,21,247.5,null],
    ["2015-08-18T13:12:33.000Z",51.368464,3.458852,7.25,14,23,247.5,null],
    ["2015-08-18T13:16:35.000Z",51.368464,3.458852,7.25,15.5,22.5,270,null],
    ["2015-08-18T13:20:35.000Z",51.368464,3.458852,8.25,17,24.5,247.5,null],
    ["2015-08-18T13:24:35.000Z",51.368464,3.458852,8,17,24.5,270,null],
    ["2015-08-18T13:28:39.000Z",51.368464,3.458852,9.75,17,24,247.5,null],
    ["2015-08-18T13:32:39.000Z",51.368464,3.458852,4.75,14.5,28,247.5,null],
    ["2015-08-18T13:36:39.000Z",51.368464,3.458852,6.25,15.5,27.5,247.5,null]
  ]
}

Last hour, csv

$ curl "http://api.pioupiou.fr/v1/archive/110?start=last-hour&stop=now&format=csv"
"License","http://developers.pioupiou.fr/data-licensing"
"Attribution","(c) contributors of the Pioupiou wind network <http://pioupiou.fr>"
"time","latitude","longitude","wind_speed_min","wind_speed_avg","wind_speed_max","wind_heading","pressure"
"utc","degrees","degrees","km/h","km/h","km/h","degrees","(deprecated)"
"2015-08-18T12:48:23.000Z",51.368464,3.458852,1,10,17.5,247.5,null
"2015-08-18T12:52:27.000Z",51.368464,3.458852,1,10.5,21,247.5,null
"2015-08-18T12:56:27.000Z",51.368464,3.458852,7,15,26,247.5,null
"2015-08-18T13:00:27.000Z",51.368464,3.458852,9.75,18.5,27,247.5,null
"2015-08-18T13:04:33.000Z",51.368464,3.458852,8,17.5,27,247.5,null
"2015-08-18T13:08:33.000Z",51.368464,3.458852,8.25,14,21,247.5,null
"2015-08-18T13:12:33.000Z",51.368464,3.458852,7.25,14,23,247.5,null
"2015-08-18T13:16:35.000Z",51.368464,3.458852,7.25,15.5,22.5,270,null
"2015-08-18T13:20:35.000Z",51.368464,3.458852,8.25,17,24.5,247.5,null
"2015-08-18T13:24:35.000Z",51.368464,3.458852,8,17,24.5,270,null
"2015-08-18T13:28:39.000Z",51.368464,3.458852,9.75,17,24,247.5,null
"2015-08-18T13:32:39.000Z",51.368464,3.458852,4.75,14.5,28,247.5,null
"2015-08-18T13:36:39.000Z",51.368464,3.458852,6.25,15.5,27.5,247.5,null

Last hour, tabulation-separated text

$ curl "http://api.pioupiou.fr/v1/archive/110?start=last-hour&stop=now&format=txt"
License:        http://developers.pioupiou.fr/data-licensing
Attribution:    (c) contributors of the Pioupiou wind network <http://pioupiou.fr>
time    latitude        longitude       wind_speed_min  wind_speed_avg  wind_speed_max  wind_heading    pressure
utc     degrees degrees km/h    km/h    km/h    degrees (deprecated)
2015-08-18T12:48:23.000Z        51.368464       3.458852        1       10      17.5    247.5   null
2015-08-18T12:52:27.000Z        51.368464       3.458852        1       10.5    21      247.5   null
2015-08-18T12:56:27.000Z        51.368464       3.458852        7       15      26      247.5   null
2015-08-18T13:00:27.000Z        51.368464       3.458852        9.75    18.5    27      247.5   null
2015-08-18T13:04:33.000Z        51.368464       3.458852        8       17.5    27      247.5   null
2015-08-18T13:08:33.000Z        51.368464       3.458852        8.25    14      21      247.5   null
2015-08-18T13:12:33.000Z        51.368464       3.458852        7.25    14      23      247.5   null
2015-08-18T13:16:35.000Z        51.368464       3.458852        7.25    15.5    22.5    270     null
2015-08-18T13:20:35.000Z        51.368464       3.458852        8.25    17      24.5    247.5   null
2015-08-18T13:24:35.000Z        51.368464       3.458852        8       17      24.5    270     null
2015-08-18T13:28:39.000Z        51.368464       3.458852        9.75    17      24      247.5   null
2015-08-18T13:32:39.000Z        51.368464       3.458852        4.75    14.5    28      247.5   null
2015-08-18T13:36:39.000Z        51.368464       3.458852        6.25    15.5    27.5    247.5   null

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/archive/999999?start=last-hour&stop=now"
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 A query argument is missing
invalid_argument 400 A query argument is invalid
request_too_large 413 You asked for more than 31 days

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

When output format is JSON, 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/archive/110?start=last-hour&stop=now&callback=myCallBackFunction"
HTTP/1.1 200 OK
Content-Type: text/javascript; charset=utf-8

/**/ typeof myCallBackFunction === 'function' && myCallBackFunction({
  "doc": "http://developers.pioupiou.fr/api/archive/",
  "license": "http://developers.pioupiou.fr/data-licensing",
  "attribution": "(c) contributors of the Pioupiou wind network <http://pioupiou.fr>",
  "legend": ["time","latitude","longitude","wind_speed_min","wind_speed_avg","wind_speed_max","wind_heading","pressure"],
  "units": ["utc","degrees","degrees","km/h","km/h","km/h","degrees","(deprecated)"],
  "data": [
    ["2015-08-18T13:36:39.000Z",51.368464,3.458852,6.25,15.5,27.5,247.5,null],
    ["2015-08-18T13:40:48.000Z",51.368464,3.458852,9,15.5,22.5,247.5,null],
    ["2015-08-18T13:44:48.000Z",51.368464,3.458852,7.75,15.5,27,247.5,null],
    ["2015-08-18T13:48:48.000Z",51.368464,3.458852,6.5,14,21.5,247.5,null],
    ["2015-08-18T13:52:47.000Z",51.368464,3.458852,10,17.5,27.5,247.5,null],
    ["2015-08-18T13:56:47.000Z",51.368464,3.458852,6.25,17,25.5,247.5,null],
    ["2015-08-18T14:00:47.000Z",51.368464,3.458852,12,18,28,247.5,null],
    ["2015-08-18T14:04:51.000Z",51.368464,3.458852,9.75,18.5,26.5,247.5,null],
    ["2015-08-18T14:08:51.000Z",51.368464,3.458852,10.5,19.5,30,225,null],
    ["2015-08-18T14:12:51.000Z",51.368464,3.458852,8.75,18.5,30.5,247.5,null],
    ["2015-08-18T14:16:55.000Z",51.368464,3.458852,7.25,16.5,24.5,247.5,null],
    ["2015-08-18T14:20:55.000Z",51.368464,3.458852,12,20,27.5,247.5,null],
    ["2015-08-18T14:24:55.000Z",51.368464,3.458852,7.25,16.5,24.5,247.5,null]
  ]
});

Limitations

Maximum request size is 31 days. You can only request data from one station at a time.

The Archive API might be slower than the other APIs.