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).

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"
  }, ...
]

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.

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.

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

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