API documentation

Data collecting API

We describe here the process to feed the noisetube server of pollution data.

  • 1/ Creating a new session of measurement, "a track":
    http://www.noisetube.net/api/newsession?key={myapikey}
  • 2/ Adding exposure data of a citizen to his/her current trace:

    example: http://www.noisetube.net/api/update?key=myapikey&l=geo:12.23,2.12&tag=klaxon&time=2008-10-02T11:02:02 Z +02:00&db=56

    where:
    Parameters Description Format Default Required
    key the API key of the submitting user     x
    db measured loudness in dB(A) an integer in [30 to 110]   x
    time local time of the measurement. W3C datetime format:
    YYYY-MM-DDThh:mm:ss Z ±hh:mm    		   x
    l Location geo:lat,lng e.g. l=geo:-12.23,2.12   x
    tag tags associated to the measurements (comma separated) free text    

  • 3/ Ends the trace (to process the data on the server VERY IMPORTANT):
    http://www.noisetube.net/api/endsesssion?key={myapikey}

That's it! You have created a trace that will be published and sharable through the website after its processing.

Access to the data commons API

Here we describe the API functions to track or get raw collected data

Function: api/search

Description: Returns the last measurements (max. 500) that match the specified criteria:

Parameters Description Format Default Required
key API key belonging to the user making the request     x
user ID or username of the user associated with the measurements      
tag tags associated with the measurements string (comma separated tags)    
city ID of the city where measurements were made integer    
geo Geographical bounding box in which measurements were made

left,bottom,right,top (e.g. geo=11.54,48.142,11.5439,48.1454)

  • left is the longitude of the left side of the bounding box.
  • bottom is the latitude of the bottom side of the bounding box.
  • right is the longitude of the right side of the bounding box.
  • top is the latitude of the top side of the bounding box.
    
dbmax maximum decibel value integer    
dbmin minimum decibel value integer    
since (Not yet implemented) measurements since this date timestamp in milliseconds    
until (Not yet implemented) measurements until this date timestamp in milliseconds    
max (Not yet implemented) the maximum number of measurements returned integer , max=100 20  
format (Not yet implemented) the output format json,rss json  

Examples:

  • The last 100th measurements in a city
    http://www.noisetube.net/api/search.json?key={apikey}&city={cityID}&max=100
  • All the measurements tagged with "neighbour" in the city ID
    http://www.noisetube.net/api/search.json?key={apikey}&tag=neighbour&city={cityID}
  • All the measurements >80 dB(a) in a given geographical area
    http://www.noisetube.net/api/search.json?key={apikey}&geo=11.54,48.142,11.5439,48.1454&dbmin=80 //
  • All the measurements >80 dB(a) in a given geographical area since a given date
    http://www.noisetube.net/api/search.json?key={apikey}&geo=11.54,48.142,11.5439,48.1454&dbmin=80&since=121212332 //

JSON Return:

dataset=[{"lat":48.8536,"lng":2.38021,"tags":[],"date":1240213058000,"l":68},
{"lat":48.8536,"lng":2.38021,"tags":[],"date":1240213067000,"l":66},
{"lat":48.8536,"lng":2.38021,"tags":["colleague"],"date":1240213268000,"l":57}]

Function: /users/{username}/tracks/{track.id}.json

Description:

Give the the measures associated to the trace with the id {trace.id} of the user {user.id}

Examples:

http://www.noisetube.net/users/nico/traces/123.json // give the associated measures of the traces with ID=123
http://www.noisetube.net/users/nico/traces/last.json // give the last trace generated by the user

JSON Return:

dataset=[{"lat":48.8536,"lng":2.38021,"tags":[],"date":1240213058000,"l":68},
{"lat":48.8536,"lng":2.38021,"tags":[],"date":1240213067000,"l":66},
{"lat":48.8536,"lng":2.38021,"tags":["colleague"],"date":1240213268000,"l":57}]