Develop

Institut für Telematik - Universität zu Lübeck

 

Note

This document is available in English only. However, you can try to translate the page with Google Translate.

The Sound of the City (SotC) project maintains a public database of geo-tagged noises and sound samples. With our REST API we are striving to achieve better access to the available data. We want other developers to participate in our project and build their own services on top of our media backend. The document at hand describes the usage of our REST interface and is intended to be a useful guide to cosume the data we serve.

We offer multiple REST resources and a variety of output formats. However, the interface is not feature-complete and may change once in a while. Please check the API version number and timestamp at the top of this page, if you encounter any problems with your code or our service.

If you have any difficulties using SotC as a developer or want to suggest new features, feel free to contact us. When writing the API documentation, we attempted to be as precise as possible. However, if anything remains unclear, we are open to recieve your feedback via email.

You can query most REST resources without any registration. However, to prevent malicious use of the SotC API, you will need an API key to report noise levels, upload sound samples or report device information. Write access is not possible, unless your application was authenticated via its application name and API key before.

Currently the use of our service is free of charge. As a developer, you can get your personal API key simply by emailing us. Please tell us a little about your project, so that we can decide whether we can provide you with authentication data or not. We reserve the right to reject issuing an API key, if we think the applicant is not trustworthy. But just give it a try, we don't bite. :-)

Client credentials must be passed in the body of your POST request:

Show sample POST body with authentication data.

{
  "Time": "1349964015",
  "NoiseLevel": 70,
  "NoiseLevelOrg": 0,
  "ReportedBy": "",
  "InPocket": 0,
  "AppName": "Foobar App Name",
  "ApiKey": "62adf8ee76d4b497dd4df5de69ca9f83"
}

This resource handles all requests related to noise levels.

https://citysound.itm.uni-luebeck.de/rest/v1.3/noiseLevels/list/?latitude=<1>&longitude=<2>&range=<3>

latitude

Latitude value of geo location (e.g. 53.834208). Decimal value in the range of +/- 90.0°. Geo locations are processed as decimal degrees.

longitude

Longitude value of geo location (e.g. 10.700136). Decimal value in the range of +/- 180.0°. Geo locations are processed as decimal degrees.

range

Lateral length of a square, which is centered on the geo location (e.g. 3.0). Decimal value. Unit is km. 0.01 degree is equal to 1.11 km, so 1 km is about 0.009 degree.

https://citysound.itm.uni-luebeck.de/rest/v1.3/noiseLevels/report/?latitude=<1>&longitude=<2>&zipCode=<3>

latitude

Latitude value of geo location (e.g. 53.834208). Decimal value in the range of +/- 90.0°. Geo locations are processed as decimal degrees.

longitude

Longitude value of geo location (e.g. 10.700136). Decimal value in the range of +/- 180.0°. Geo locations are processed as decimal degrees.

zipCode

Zip code of target area (e.g. 23562). String value with a maximum length of ten characters. This parameter is optional.

This is a POST request with body payload. If you want to report noise levels, please use your API key for authentification.

Time

Time of the reporting. UNIX timestamp as a string value with a maximum length of 80 characters.

NoiseLevel

Reported noise level value. Integer number with dB as its unit.

NoiseLevelOrg

Reported noise level value. Integer number with dB as its unit. Pass 0, unless you know how this argument is used internally.

ReportedBy

Identifier for client that reported the noise level. String value with a maximum length of 80 characters. Pass an empty string, unless you know how this argument is used internally.

InPocket

Flag to indicate that the user's device was in his or hers pocket while recording. This may indicate that the reported value is inaccurate. Integer number to represent a boolean value (0 for false and 1 for true). Pass zero, unless you know how this argument is used internally.

AppName

Identifier for application that reports the noise level. String value with a maximum length of 80 characters. The application name is case sensitive. You need to apply for an API key, before you can issue POST requests.

ApiKey

API key that matches your application's name. String value with a maximum length of 32 characters. You need to apply for an API key, before you can issue POST requests.

In the following code box you can see a sample POST request for noise level reporting:

Show JSON payload of REST request.

{
  "Time": "1350082846",
  "NoiseLevel": 70,
  "NoiseLevelOrg": 0,
  "ReportedBy": "",
  "InPocket": 0,
  "AppName": "Foobar App Name",
  "ApiKey": "62adf8ee76d4b497dd4df5de69ca9f83"
}

This resource handles all requests related to sound samples.

https://citysound.itm.uni-luebeck.de/rest/v1.3/soundSamples/list/?latitude=<1>&longitude=<2>&range=<3>

latitude

Latitude value of geo location (e.g. 53.834208). Decimal value in the range of +/- 90.0°. Geo locations are processed as decimal degrees.

longitude

Longitude value of geo location (e.g. 10.700136). Decimal value in the range of +/- 180.0°. Geo locations are processed as decimal degrees.

range

Lateral length of a square, which is centered on the geo location (e.g. 3.0). Decimal value. Unit is km. 0.01 degree is equal to 1.11 km, so 1 km is about 0.009 degree.

Show JSON payload of REST response.

{
  "Statuscode": "OK",
  "Message": "Sound samples queried successfully.",
  "SampleData": {
    "0": {
      "Latitude": "51.58000",
      "Longitude": "7.60000",
      "Title": "Construction site",
      "Timestamp": "1349964015",
      "Description": "Drill on a construction site.",
      "Tag": "construction",
      "SampleID": "1ceb8089e7441732e10866019101e44f"
    },
    "1": {
      "Latitude": "51.58000",
      "Longitude": "7.60000",
      "Title": "Car sound",
      "Timestamp": "1350092454",
      "Description": "A Ferrari in the city.",
      "Tag": "car",
      "SampleID": "b64f3dbd20329d9af01ff21eed64ff0c"
    },
    "2": {
      "Latitude": "51.58000",
      "Longitude": "7.60000",
      "Title": "Ducks",
      "Timestamp": "1350082846",
      "Description": "A group of ducks in the city park.",
      "Tag": "nature",
      "SampleID": "5851478d17719a6beaf3eeeff03d6a46"
    }
  },
  "ResultCount": 3
}

Show XML payload of REST response.

<Response>
  <Statuscode>OK</Statuscode>
  <Message>Sound samples queried successfully.</Message>
  <SampleData>
    <Item>
      <Latitude>51.58000</Latitude>
      <Longitude>7.60000</Longitude>
      <Title>Construction site</Title>
      <Timestamp>1349964015</Timestamp>
      <Description>Drill on a construction site.</Description>
      <Tag>construction</Tag>
      <SampleID>1ceb8089e7441732e10866019101e44f</SampleID>
    </Item>
    <Item>
      <Latitude>51.58000</Latitude>
      <Longitude>7.60000</Longitude>
      <Title>Car sound</Title>
      <Timestamp>1350092454</Timestamp>
      <Description>A Ferrari in the city.</Description>
      <Tag>car</Tag>
      <SampleID>b64f3dbd20329d9af01ff21eed64ff0c</SampleID>
    </Item>
    <Item>
      <Latitude>51.58000</Latitude>
      <Longitude>7.60000</Longitude>
      <Title>Ducks</Title>
      <Timestamp>1350092454</Timestamp>
      <Description>A group of ducks in the city park.</Description>
      <Tag>nature</Tag>
      <SampleID>b64f3dbd20329d9af01ff21eed64ff0c</SampleID>
    </Item>
  </SampleData>
  <ResultCount>3</ResultCount>
</Response>

https://citysound.itm.uni-luebeck.de/rest/v1.3/soundSamples/upload/?latitude=<1>&longitude=<2>

latitude

Latitude value of geo location (e.g. 53.834208). Decimal value in the range of +/- 90.0°. Geo locations are processed as decimal degrees.

longitude

Longitude value of geo location (e.g. 10.700136). Decimal value in the range of +/- 180.0°. Geo locations are processed as decimal degrees.

This is a POST request with body payload. If you want to upload sound samples, please use your API key for authentification.

Title

Short title for the sound sample. String value with a maximum length of 255 characters. This parameter is optional.

Time

Time of the sound sample recording. UNIX timestamp as a string value with a maximum length of 80 characters.

Description

Detailed description of the sound sample. String value with no limitation on the text length. This parameter is optional.

Tag

Descriptive tag for content of sound sample. String value. Either one of car, train, people, nature, music, plane, construction, church, ship or other.

PayloadType

Identifier for the audio format that was used to encode the sound sample. String value. Either one of mp3, m4a or ogg.

Payload

Base64-encoded binary data of the sound sample. String value with no limitation on the text length. However, the upload of very huge files may fail. The service was designed for short audio files and works best with files that have a size of about 3 MB or less.

ReportedBy

Identifier for client that uploaded the sound sample. String value with a maximum length of 80 characters. Pass an empty string, unless you know how this argument is used internally.

AppName

Identifier for application that uploads the sound sample. String value with a maximum length of 80 characters. The application name is case sensitive. You need to apply for an API key, before you can issue POST requests.

ApiKey

API key that matches your application's name. String value with a maximum length of 32 characters. You need to apply for an API key, before you can issue POST requests.

In the following code box you can see a sample POST request for sound sample uploading:

Show JSON payload of REST request.

{
  "Title": "Church bell",
  "Time": "1350164562",
  "Tag": "church",
  "Description": "Hear the church bells ring.",
  "PayloadType": "mp3",
  "Payload": "<Base64-encoded Sound Sample>",
  "ReportedBy": "",
  "AppName": "Foobar App Name",
  "ApiKey": "62adf8ee76d4b497dd4df5de69ca9f83"
}

This resource handles all requests related to device information.

https://citysound.itm.uni-luebeck.de/rest/v1.3/deviceInfos/report/

This is a POST request with body payload. If you want to report device information, please use your API key for authentification.

OSVersion

Version number of the device's operating system (e.g. 2.6.35.7-perf). String value with a maximum length of 80 characters.

APILevel

API level of the device's operating system (e.g. 10). String value with a maximum length of 20 characters.

DeviceType

Type of the user's device (e.g. GT-I9001). String value with a maximum length of 80 characters.

ReportedBy

Identifier for client that reported the device information. String value with a maximum length of 80 characters. Pass an empty string, unless you know how this argument is used internally.

AppName

Identifier for application that reports the device information. String value with a maximum length of 80 characters. The application name is case sensitive. You need to apply for an API key, before you can issue POST requests.

ApiKey

API key that matches your application's name. String value with a maximum length of 32 characters. You need to apply for an API key, before you can issue POST requests.

In the following code box you can see a sample POST request for device information reporting:

Show JSON payload of REST request.

{
  "OSVersion": "2.6.35.7-perf",
  "APILevel": "10",
  "DeviceType": "GT-I9001",
  "ReportedBy": "",
  "AppName": "Foobar App Name",
  "ApiKey": "62adf8ee76d4b497dd4df5de69ca9f83"
}

This resource handles all requests related to use statistics.

https://citysound.itm.uni-luebeck.de/rest/v1.3/useStats/count/?what=<1>&when=<2>&from=<3>&to=<4>

https://citysound.itm.uni-luebeck.de/rest/v1.3/useStats/summary/?what=<1>

Show JSON payload of REST response.

{
  "Statuscode": "OK",
  "Message": "Statistics summary queried successfully.",
  "StatisticsSummary": {
    "ContentType": "noiseLevels",
    "NowTimestamp": "1361798647",
    "SummaryData": {
      "Today": {
        "0": {
          "Date": "2013-02-25, 00:00:00",
          "ReportsCounter": "0"
        },
        "1": {
          "Date":" 2013-02-25, 01:00:00",
          "ReportsCounter": "0"
        },
        "2": {
          "Date": "2013-02-25, 02:00:00",
          "ReportsCounter": "0"
        },
        "3": {
          "Date": "2013-02-25, 03:00:00",
          "ReportsCounter": "0"
        },
        "4": {
          "Date": "2013-02-25, 04:00:00",
          "ReportsCounter": "0"
        },
        "5": {
          "Date": "2013-02-25, 05:00:00",
          "ReportsCounter": "0"
        },
        "6": {
          "Date": "2013-02-25, 06:00:00",
          "ReportsCounter": "0"
        },
        "7": {
          "Date": "2013-02-25, 07:00:00",
          "ReportsCounter": "0"
        },
        "8": {
          "Date": "2013-02-25, 08:00:00",
          "ReportsCounter": "0"
        },
        "9": {
          "Date": "2013-02-25, 09:00:00",
          "ReportsCounter": "0"
        },
        "10": {
          "Date": "2013-02-25, 10:00:00",
          "ReportsCounter": "0"
        },
        "11": {
          "Date": "2013-02-25, 11:00:00",
          "ReportsCounter": "0"
        },
        "12": {
          "Date": "2013-02-25, 12:00:00",
          "ReportsCounter": "0"
        },
        "13": {
          "Date": "2013-02-25, 13:00:00",
          "ReportsCounter": "0"
        },
        "14": {
          "Date": "2013-02-25, 14:00:00",
          "ReportsCounter": "0"
        },
        "15": {
          "Date": "2013-02-25, 15:00:00",
          "ReportsCounter": "0"
        },
        "16": {
          "Date": "2013-02-25, 16:00:00",
          "ReportsCounter": "0"
        },
        "17": {
          "Date": "2013-02-25, 17:00:00",
          "ReportsCounter": "0"
        },
        "18": {
          "Date": "2013-02-25, 18:00:00",
          "ReportsCounter": "0"
        },
        "19": {
          "Date": "2013-02-25, 19:00:00",
          "ReportsCounter": "0"
        },
        "20": {
          "Date": "2013-02-25, 20:00:00",
          "ReportsCounter": "0"
        },
        "21": {
          "Date": "2013-02-25, 21:00:00",
          "ReportsCounter": "0"
        },
        "22": {
          "Date": "2013-02-25, 22:00:00",
          "ReportsCounter": "0"
        },
        "23": {
          "Date": "2013-02-25, 23:00:00",
          "ReportsCounter": "0"
        }
      },
      "LastMonths": {
        "0": {
          "Month": "2012-03",
          "ReportsCounter": "0"
        },
        "1": {
          "Month": "2012-04",
          "ReportsCounter": "0"
        },
        "2": {
          "Month": "2012-05",
          "ReportsCounter": "6008"
        },
        "3": {
          "Month": "2012-06",
          "ReportsCounter": "647"
        },
        "4": {
          "Month": "2012-07",
          "ReportsCounter": "6689"
        },
        "5": {
          "Month": "2012-08",
          "ReportsCounter": "3131"
        },
        "6": {
          "Month": "2012-09",
          "ReportsCounter": "2368"
        },
        "7": {
          "Month": "2012-10",
          "ReportsCounter": "28152"
        },
        "8": {
          "Month": "2012-11",
          "ReportsCounter": "71987"
        },
        "9": {
          "Month": "2012-12",
          "ReportsCounter": "18"
        },
        "10": {
          "Month": "2013-01",
          "ReportsCounter": "112"
        },
        "11": {
          "Month": "2013-02",
          "ReportsCounter": "513"
        }
      }
    }
  }
}

Show XML payload of REST response.

<Response>
  <Statuscode>OK</Statuscode>
  <Message>Statistics summary queried successfully.</Message>
  <StatisticsSummary>
    <ContentType>noiseLevels</ContentType>
    <NowTimestamp>1361798647</NowTimestamp>
    <SummaryData>
      <Today>
        <Item>
          <Date>2013-02-25, 00:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 01:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 02:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 03:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 04:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 05:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 06:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 07:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 08:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 09:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 10:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 11:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 12:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 13:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 14:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 15:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 16:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 17:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 18:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 19:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 20:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 21:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 22:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Date>2013-02-25, 23:00:00</Date>
          <ReportsCounter>0</ReportsCounter>
        </Item>
      </Today>
      <LastMonths>
        <Item>
          <Month>2012-03</Month>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Month>2012-04</Month>
          <ReportsCounter>0</ReportsCounter>
        </Item>
        <Item>
          <Month>2012-05</Month>
          <ReportsCounter>6008</ReportsCounter>
        </Item>
        <Item>
          <Month>2012-06</Month>
          <ReportsCounter>647</ReportsCounter>
        </Item>
        <Item>
          <Month>2012-07</Month>
          <ReportsCounter>6689</ReportsCounter>
        </Item>
        <Item>
          <Month>2012-08</Month>
          <ReportsCounter>3131</ReportsCounter>
        </Item>
        <Item>
          <Month>2012-09</Month>
          <ReportsCounter>2368</ReportsCounter>
        </Item>
        <Item>
          <Month>2012-10</Month>
          <ReportsCounter>28152</ReportsCounter>
        </Item>
        <Item>
          <Month>2012-11</Month>
          <ReportsCounter>71987</ReportsCounter>
        </Item>
        <Item>
          <Month>2012-12</Month>
          <ReportsCounter>18</ReportsCounter>
        </Item>
        <Item>
          <Month>2013-01</Month>
          <ReportsCounter>112</ReportsCounter>
        </Item>
        <Item>
          <Month>2013-02</Month>
          <ReportsCounter>513</ReportsCounter>
        </Item>
      </LastMonths>
    </SummaryData>
  </StatisticsSummary>
</Response>