Skip to content

Smell PGH API

Jump to bottom
Mike Tasota edited this page Apr 23, 2018 · 1 revision

Smell Pittsburgh API

Contents

Exposed API

/api/v2/regions
/api/v2/regions/:id
/api/v2/regions/:id/map_markers
/api/v2/regions/:id/zip_codes
/api/v2/zip_codes
/api/v2/clients
/api/v2/smell_reports (GET, POST)
/api/v2/get_aqi

API Endpoints

  • GET /api/v2/regions
    • format: JSON Array [ {id,latitude,longitude,zoom_level,name,created_at,updated_at} ]
    • description: Requests a list of all Region records.
  • GET /api/v2/regions/:id
    • format: JSON {id,latitude,longitude,zoom_level,name,created_at,updated_at}
    • description: Requests the Region record with matching id.
  • GET /api/v2/regions/:id/map_markers
    • format: JSON Array [ {id,latitude,longitude,marker_type,data*} ]
      • *NOTE: MapMarker record gets merged with its data blob, so other fields are possible.
    • description: Requests MapMarker records belonging to Region specified by id.
  • GET /api/v2/regions/:id/zip_codes
    • format: String Array
    • description: Requests a list of zipcodes that are part of Region specified by id.
  • GET /api/v2/zip_codes
    • format: JSON Array [ {id,zip} ]
    • description: Requests a list of all zipcodes stored the database. A zipcode is stored in the database if a smell report was submitted within it.
  • GET /api/v2/clients
    • format: JSON Array [ {id,name,created_at} ]
    • description: Requests a list of all Client records.
  • GET /api/v2/smell_reports
    • format: JSON Array
    • description: Requests a list of all SmellReport records, with given constraints.
    • parameters:
      • start_time: The earliest accepted value of observed_at in epoch time for smell reports. Defaults to 0.
      • end_time: The latest accepted value of observed_at in epoch time for smell reports. Defaults to the current time (on server).
      • region_ids: A comma-separated list of IDs of regions that smell reports must be contained within. This is determined by zipcode.
      • client_ids: A comma-separated list of IDs for clients that smell reports must have been submitted from.
      • smell_value: A comma-separated list of accepted values for smell_value of the smell reports. Order of the numbers is not relevant. Defaults to be non-restrictive ("1,2,3,4,5").
      • latlng_bbox: If provided, restrict the smell reports returned by their perturbed latitude and longitude values to be within a bounding box. This bounding box is specified by a comma-separated list of four numbers. The first two numbers are the latitude and longitude of the top-left corner of the bounding box, and the last two ares are the latitude and longitude of the bottom-right corner of the bounding box.
      • group_by: Group the results by zipcode, month, or day.
      • aggregate: If set to True, print the results as a total count instead of a list of each individual record.
      • zipcodes: A comma-separated list of zipcodes, defined by their zip (not by the zip_code ID in the database).
      • format: Currently supports either CSV or JSON.
  • POST /api/v2/smell_reports
    • description: Create a new SmellReport record. This requires a valid client_token to be passed in, which is associated with a Client in the database.
    • parameters (old):
      • latitude: An accurate latitude coordinate for the location that the report pertains to. This becomes perturbed within one-tenth of a mile when later requested by the API.
      • longitude: An accurate longitude coordinate for the location that the report pertains to. This becomes perturbed within one-tenth of a mile when later requested by the API.
      • user_hash: A randomly-generated string that anonymously identifies a user. It is up to the Client to implement generating these hashes uniquely per user.
      • smell_value: An integer between 1 and 5 that is associated with the report. For Smell PGH, the values 1-5 correlate to the phrases: "1 Just fine!", "2 Barely noticeable", "3 Definitely noticeable", "4 It's getting pretty bad", "5 About as bad as it gets!"
      • (optional)
      • smell_description: A description of the smell or odor related to the report.
      • feelings_symptoms: Symptoms linked to the smell or odor.
      • additional_comments: A string that serves as a "miscellaneous" field for additional comments that do not fall into the standard value/description/symptoms categories. The use of this field is dependent on the Client. Some may choose to use it as a JSON blob to provide several extra input options for its users.
      • custom_location: A boolean value indicating if the user is submitting the report retroactively (i.e. from a location other than the device's current location). Defaults to false
      • custom_time: A boolean value indicating if the user is submitting the report retroactively (i.e. at a time other than the current time). Defaults to false
      • observed_at: The time that the reported incident was observed at, formatted as a string (defined by RFC 3339). Defaults to the current time. Note If custom_time is not set (or is set to false) the value for this field will be ignored and still default to the current time.
      • send_form_to_agency: A boolean value indicating if the report should be submitted to each Agency associated with the Region from which the smell report incident occurred. Defaults to true
      • email: The email address for the user to be contacted (and sent to Agency if send_form_to_agency is set to true).
      • name: The name for the user to be contacted (and sent to Agency if send_form_to_agency is set to true).
      • phone_number: The phone number for the user to be contacted (and sent to Agency if send_form_to_agency is set to true).
      • address: The postal address for the user to be contacted (and sent to Agency if send_form_to_agency is set to true).
    • parameters (new):
      • client_token: A string that uniquely identifies an authorized Client. A smell report will not be accepted unless a valid token is provided.
      • (optional)
      • debug_info: A JSON blob associated with the report used for debugging purposes. This is not currently accessible outside of the internal database (i.e. non-API accessible).
  • GET /api/v2/get_aqi
    • format: Number
    • description: Looks up AQI for a specified city.
    • parameters:
      • city: The city to look up the AQI for. Cities specified in the code include: Pittsburgh, New York City, Boston, Cleveland, Chicago, Seattle, San Francisco, Washington DC, Denver, Columbus, Houston, Los Angeles, Philadelphia. Note these are case-sensitive.
Clone this wiki locally