Use the API to find, use, and manage Data Sources.
Base URL
https://data-sources.pdap.io/api
Search Tokens
Generate API token for front end search
GET[base-url]/search-tokens
The search tokens endpoint is located in resources/SearchTokens.py. The search tokens endpoint generates an API token valid for 5 minutes and forwards the search parameters to the Quick Search endpoint. This endpoint is meant for use by the front end only.
Query Parameters
Name
Type
Description
arg1*
String
The first argument that will be forwarded on to the appropriate endpoint. Currently either "search" for quick-search or "id" for data-sources
arg2*
String
The second argument that will be forwarded on to the appropriate endpoint. Currently just used for "location" for quick-search
endpoint
String
The endpoint that will be accessed after a search token is generated
{"count":1,"data": [ {"agency_name":"Allegheny County Police Department - PA","municipality":"Pittsburgh","state_iso":"PA","data_source_name":"Allegheny County Police Review Board Transcripts","description":null,"record_type":"Policies & Contracts","source_url":"https://www.alleghenycounty.us/county-council/police-review-board-meetings.aspx","record_format":"[\"PDF: Machine Created\"]","coverage_start":"2018-08-29","coverage_end":"2018-09-26","agency_supplied":true } ]}
{"message": error}
Search
Quick Search Data Sources by search term and location
GET[base-url]/quick-search/{search}/{location}
The quick search endpoint is located in resources/QuickSearch.py. The quick search endpoint executes its search using the agency_source_link table in the Data Sources database, which links each data source in the data_sources table with its associated agency in the agencies table. This endpoint is meant for use by the search tokens endpoint only.
Path Parameters
Name
Type
Description
search*
String
Checks partial matches on any of the following properties on the data_source table: "name", "description", "record_type", and "tags". The search term will is case insensitive and will match singular and pluralized versions of the term.
location*
String
Checks partial matches on any of the following properties on the agencies table: "county_name", "state_iso", "municipality", "agency_type", "jurisdiction_type", "name"
Headers
Name
Type
Description
Authorization*
String
Value formatted as "Bearer [access token/api key]”
{"count":1,"data": [ {"agency_name":"Allegheny County Police Department - PA","municipality":"Pittsburgh","state_iso":"PA","data_source_name":"Allegheny County Police Review Board Transcripts","description":null,"record_type":"Policies & Contracts","source_url":"https://www.alleghenycounty.us/county-council/police-review-board-meetings.aspx","record_format":"[\"PDF: Machine Created\"]","coverage_start":"2018-08-29","coverage_end":"2018-09-26","agency_supplied":true } ]}
{
"count": 0,
"message": error
}
{// Response}
Data Sources
Get all Data Sources
GET[base-url]/data-sources
The data sources endpoint is located in resources/DataSources.py. The data sources endpoint returns all approved rows in the corresponding Data Sources database table by default. An optional JSON object can be passed to get data sources needing identification instead.
Headers
Name
Type
Description
Authorization*
String
Value formatted as "Bearer [access token/api key]”
Request Body
Name
Type
Description
Data
JSON
In order to get data sources needing identification: {"approved": False}
{"count": 0,"message": "There has been an error pulling data!"}
Data Sources for Map
GET[base-url]/data-sources-map
Headers
The data sources for map endpoint is located in resources/DataSourcesMap.py. The data sources endpoint returns all approved rows in the corresponding Data Sources database table by default with only the columns relevant to mapping.
Name
Type
Description
Authorization*
String
Value formatted as "Bearer [access token/api key]”
{"count": 0,"message": "There has been an error pulling data!"}
Get Data Source by Id
GET[base-url]/data-sources-by-id/[id]
The data sources endpoint is located in resources/DataSources.py. The data source by id endpoint returns just the row for the data source that corresponds to the id passed.
Path Parameters
Name
Type
Description
id*
String
Data source id
Headers
Name
Type
Description
Authorization*
String
Value formatted as "Bearer [access token/api key]”
{"message": "There has been an error pulling data!"}
{"message": "Data source not found."}
Create Data Source
POST[base-url]/data-sources
The data sources endpoint is located in resources/DataSources.py. The create data source endpoint posts a new data source to the database and returns True if successful and False if not.
Headers
Name
Type
Description
Authorization*
String
Value formatted as "Bearer [access token/api key]”
Request Body
Name
Type
Description
Data
JSON
A JSON object of the data source information. Refer to the Data Source dictionary for available fields: https://docs.pdap.io/activities/data-dictionaries/data-sources-data-dictionary. However, the following fields cannot be edited: rejection_note, data_source_request, approval_status, airtable_uid, airtable_source_last_modified
Below is an example of an acceptable body:
{ "name": "Calls for Service for Chicago Police Department - IL",
{"message": "There has been an error adding the data source"}
{// Response}
Update Data Source by Id
PUT[base-url]/data-sources-by-id/[id]
The data sources endpoint is located in resources/DataSources.py. The update data source by id endpoint updates a data source and returns a status to confirm a successful update.
Path Parameters
Name
Type
Description
id*
String
Data source id
Headers
Name
Type
Description
Authorization*
String
Value formatted as "Bearer [access token/api key]”
{"message": "There has been an error updating the data source"}
{// Response}
{// Response}
Archives
Get all Archived urls
GET[base-url]/archives
The archives endpoint is located in resources/Archives.py. The get method on the archives endpoint returns all rows for urls that the automatic archives script has cached in the Internet Archive.
Headers
Name
Type
Description
Authorization*
String
Value formatted as "Bearer [access token/api key]”
id stringsource_url stringupdate_frequency stringlast_cached string
The archives endpoint is located in resources/Archives.py. The put method on the archives endpoint updates the data source matching the passed id, updating the last_cached date if it alone is passed, or it and the broken_source_url_as_of field and the url_status to 'broken'.
Headers
Name
Type
Description
Authorization*
String
Value formatted as "Bearer [access token/api key]”
Request Body
Name
Type
Description
id*
String
The airtable uid for the data source that was cached
broken_source_url_as_of*
Date
The current date if the url is no longer active, otherwise None
last_cached*
Date
The current date since the data source url was just cached in the Internet Archive
The agencies endpoint is located in resources/Agencies.py. The agencies endpoint returns 1000 rows from the corresponding Data Sources database table offset by the page number passed.
Path Parameters
Name
Type
Description
page*
String
Passing 1 will return the first 1000 rows. Subsequent page number return subsequent results
Headers
Name
Type
Description
Authorization
String
Value formatted as "Bearer [access token/api key]”