How to use the API

This guide will describe how to interact with the Smell PGH API to request smell reports as well as how to create new smell reports (for certified clients).

Get Smell Reports

All smell reports that are submitted are accessible in the API. As a quick demo, the following request will return all smell reports from 2016 with smell values 4 or higher:

curl https://api.smellpittsburgh.org/api/v2/smell_reports?smell_value=4,5&start_time=1451606400&end_time=1483228800

The returned result will look something like:

[
  {
    "zip_code_id" : 2,
    "latitude" : 40.4111,
    "feelings_symptoms" : null,
    "observed_at" : 1469198345,
    "zipcode" : "15213",
    "smell_value" : 4,
    "longitude" : -79.9411,
    "smell_description" : "woodsmoke"
  }, ...
]

Get Smell Reports based on Client or Region

If you are only interested in reports that belong to a specific Region or were submitted by a particular Client, you can use the region_ids and client_ids parameters. To see an index of available Regions and Clients, you can access their respective API endpoints.

curl https://api.smellpittsburgh.org/api/v2/clients

curl https://api.smellpittsburgh.org/api/v2/regions

For other parameters for filtering smell report results, visit the Smell PGH API page.

Regions

Currently, a Region is defined by a list of ZipCodes. Regions connect smell reports with agencies as well as provide some context for the smell reports through MapMarkers.

A MapMarker represents a location that may be relevant to be drawn on a map alongside smell reports. Examples include federal sensors (PM, VOC, SO2), locations of interest (of potential pollutants), or other static locations.

Map markers for a Region

To see all map markers for a Region, use the API endpoint (using Allegheny County id=1 as an example):

curl https://api.smellpittsburgh.org/api/v2/regions/1/map_markers

Create Smell Reports (requires a Client token)

Every submitted smell report is associated with an authorized Client, which is identified by a unique client_token that is sent along with the smell report form.

{
  "latitude" : 40.443403,
  "longitude" : -79.94564,
  "user_hash" : "test-01234567890",
  "smell_value" : 1,
  "client_token" : "clientToken"
}

curl -X POST https://api.smellpittsburgh.org/api/v2/smell_reports -d @params.json