SparkmapApi
API Documentation
Contents
1. Overview
SparkMap API is a JSON-based REST API. All requests are made to endpoints beginning:
https://api.sparkmap.org/indicator/v1
The API is arranged around resources. All requests must be made with an access token.
Typically, the first request you make should be to acquire location types that your token can access. This will confirm that your access token is valid, and give you a list of location types that you will need for subsequent requests.
The indicator data resources give you access to the metrics for one or all indicators. You may request the data in JSON or Comma Separated Value (CSV) format.
The indicator info resources give you detailed information about each indicator, including a unique identifer for the indicator and its supplemental breakouts, indicator name, data category, attributes, geographic availability, and source information.
2. Authentication
In order to access SparkMap API, you will need an access token. A token grants access to data for a specific list of indicators and geographic locations. Contact us to get a subscription or testing access token.
3. Resources
3.1. Location types
Get a list of geographic location types accessible by your token.
Two response options are provided: JSON and Comma Separated Values (CSV).
3.1.1. JSON response
Get location types in JSON format:
The request to fetch location types may have the following parameters:
| Parameter | Type | Required? | Description |
|---|---|---|---|
token |
string | required | The access token you received. |
include_locations |
bool | optional | Whether to return all location items for each location type. Defaults to false. |
Get location types without location items:
GET https://api.sparkmap.org/indicator/v1/locations?token={{token}}
Get location types with location items:
GET https://api.sparkmap.org/indicator/v1/locations?token={{token}}&include_locations=true
The response is a list of location type objects.
Example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"location_key": "county",
"title": "My counties",
"location_count": 2,
"locations": [
{
"location_id": "01001",
"location_name": "Autauga County, AL"
},
{
"location_id": "01003",
"location_name": "Baldwin County, AL"
}
]
},
{
"location_key": "state",
"title": "My state",
"location_count": 1,
"locations": [
{
"location_id": "01",
"location_name": "Alabama"
}
]
},
{
"location_key": "us",
"title": "United States",
"location_count": 1,
"locations": [
{
"location_id": "0",
"location_name": "United States"
}
]
}
]
Where a location type object is:
| Field | Type | Description |
|---|---|---|
| location_key | string | A unique key of the location type |
| title | string | A descriptive title of the location type |
| location_count | int | Number of location items of the location type |
| locations | list | Full list of location item objects of the location type |
Where a location item object is:
| Field | Type | Description |
|---|---|---|
| location_id | string | A unique identifer of the location item |
| location_name | string | Name of the location item |
Possible errors:
| Error code | Description |
|---|---|
| 401 Unauthorized | The token is invalid or has expired |
Get location types filtered by type and state in JSON format:
To fetch a subset of location types use the following parameters:
| Parameter | Type | Description |
|---|---|---|
token |
string | The access token you received. |
include_locations |
bool | Specify true to receive geography item info. |
location_key |
string | Specify the location type to fetch, like county or uscong. |
state |
string | Specify the state to get matching geographies in that state. Use two-letter abbreviations (CA for California) or the state’s FIPS code (06 for California). |
3.1.2 CSV response
Get location types in CSV format:
The request to fetch location types in CSV format has only one parameter token:
GET https://api.sparkmap.org/indicator/v1/locations.csv?token={{token}}
The response is a text string formatted as CSV output, including location_key, title, and location_count. No location items are returned.
Example response:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
location_key,title,location_count
county,My counties,2
state,My state,1
us,United States,1
Possible errors:
| Error code | Description |
|---|---|
| 401 Unauthorized | The token is invalid or has expired |
3.2. Indicator data
Get indicator data
Returns a full list of indicator data for all locations accessible by the token. Optionally, returns indicator data for a specific indicator or breakout, or for a specific location, or for all locations within one or more states.
Each request is limited to fetch data for up to 1,000 locations for any location type. For location types with more than 1,000 locations, e.g. counties or ZIP Codes in the U.S., we recommend sending requests to fetch data by state with the state parameter.
The request to fetch indicator data may have the following parameters:
| Parameter | Type | Required? | Description |
|---|---|---|---|
token |
string | required | The access token you received. |
location_key |
string | optional | The key of the geographic location type to get indicator data for, e.g. county, state. See location_key property in the response object from the Location Types resource above. Defaults to the key of first location type. |
location_id |
string | optional | The unique location identifer to limit the indicator data returned, e.g. county fips codes: 29019. See location_id property in the response object from the Location Types resource above. To request data for more than one location ID, include them as a comma-separated string, like x,y,z. |
indicator_id |
int | optional | The unique identifier of an indicator. If omitted, all indicator data are returned. Multiple IDs may be passed as a comma-separated string, like x,y,z. |
breakout_id |
int | optional | The unique identifier of a breakout indicator. If omitted, all breakout data are returned. Set to 0 to exclude all breakouts. Multiple IDs may be passed as a comma-separated string, like x,y,z. |
state |
string | optional | The census code or name of a state to limit the indicator data returned, e.g. Missouri, MO, 29, 04000US29. |
All parameters are query string parameters, appearing after a question mark (?) in the endpoint. In the query string, each parameter is listed one right after the other with an ampersand (&) separating them. The order of the query string parameters does not matter.
Two response options are provided: JSON and Comma Separated Values (CSV). The two options use the same parameters listed above. Use any combination of the optional parameters to limit response data to specific indicators or locations.
3.2.1. JSON response
Get a full list of indicator data for up to 1,000 locations of the default location type:
GET https://api.sparkmap.org/indicator/v1/data?token={{token}}
Get a full list of indicator data for one or more location types (up to 1,000 locations for each location type):
GET https://api.sparkmap.org/indicator/v1/data?token={{token}}&location_key={{location_key}}
Examples:
https://api.sparkmap.org/indicator/v1/data?token={{token}}&location_key=state
https://api.sparkmap.org/indicator/v1/data?token={{token}}&location_key=county,state,us
Get a full list of indicator data for one or more specific locations:
GET https://api.sparkmap.org/indicator/v1/data?token={{token}}&location_id={{location_id}}
Example: https://api.sparkmap.org/indicator/v1/data?token={{token}}&location_id=01001,01003
Get indicator data for a specific indicator:
GET https://api.sparkmap.org/indicator/v1/data?token={{token}}&indicator_id={{location_id}}
Example for fetching indicator data with all supplemental breakouts:
https://api.sparkmap.org/indicator/v1/data?token={{token}}&indicator_id=700
Example for fetching indicator data without supplemental breakout:
https://api.sparkmap.org/indicator/v1/data?token={{token}}&indicator_id=700&breakout_id=0
Get indicator data for a specific breakout indicator:
GET https://api.sparkmap.org/indicator/v1/data?token={{token}}&breakout_id={{breakout_id}}
Example: https://api.sparkmap.org/indicator/v1/data?token={{token}}&breakout_id=3700
Get all indicator data for one or more states:
GET https://api.sparkmap.org/indicator/v1/data?token={{token}}&state={{state}}
Example: GET https://api.sparkmap.org/indicator/v1/data?token={{token}}&state=AL,CA
The response is a list of indicator data objects.
Example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"indicator_id": 700,
"name": "Total Population",
"data": [
{
"Location Id": "01001",
"Location Name": "Autauga County, AL",
"Total Population": 55380,
"Total Land Area (Square Miles)": 593.44,
"Population Density (Per Square Mile)": 93.16
},
{
"Location Id": "01003",
"Location Name": "Baldwin County, AL",
"Total Population": 212830,
"Total Land Area (Square Miles)": 1589.79,
"Population Density (Per Square Mile)": 133.87
}
],
"category": "Demographics",
"source": "US Census Bureau, <a href=\"https://www.census.gov/programs-surveys/acs/\">American Community Survey</a>.",
"source_date": "2015-19."
},
{
"indicator_id": 700,
"breakout_id": 3702,
"name": "Total Population by Gender",
"data": [
{
"Location Id": "01001",
"Location Name": "Autauga County, AL",
"Male": 26934,
"Female": 28446,
"Male, Percent, %": 48.63,
"Female, Percent, %": 51.37
},
{
"Location Id": "01003",
"Location Name": "Baldwin County, AL",
"Male": 103496,
"Female": 109334,
"Male, Percent, %": 48.63,
"Female, Percent, %": 51.37
}
]
}
]
Where an indicator data object is:
| Field | Type | Description |
|---|---|---|
| indicator_id | int | A unique identifer for the indicator |
| breakout_id | int | A unique identifer for the indicator as a supplemental breakout indicator |
| name | string | Name of the indicator |
| data | list | A list of data objects for all locations requested |
| category | string | Category of the indicator |
| source | string | Source of the indicator data |
| source_date | string | Source date of the indicator data |
Where a data object for each location is:
| Field | Type | Description |
|---|---|---|
| Location Id | string | A unique identifer for the location |
| Location Name | string | Name of the location |
{{attribute name}} |
object | Name and value for the attribute |
Possible errors:
| Error code | Description |
|---|---|
| 401 Unauthorized | The token is invalid or has expired |
| 400 Bad Request | The inputs supplied to the API are invalid |
| 404 Not Found | No indicators or location items are found for the request |
3.2.2. CSV response
The request to fetch indicator data in CSV format uses the same parameters as the request for JSON response option, as listed above. Use any combination of the optional parameters to limit response data to specific indicators or locations. Each request is limited to fetch data for up to 1,000 locations for any location type.
Get a full list of indicator data for up to 1,000 locations of the default location type:
GET https://api.sparkmap.org/indicator/v1/data.csv?token={{token}}
Get a full list of indicator data for one or more location types (up to 1,000 locations for each type):
GET https://api.sparkmap.org/indicator/v1/data.csv?token={{token}}&location_key={{location_key}}
Get a full list of indicator data for a specific location:
GET https://api.sparkmap.org/indicator/v1/data.csv?token={{token}}&location_id={{location_id}}
Get indicator data for a specific indicator:
GET https://api.sparkmap.org/indicator/v1/data.csv?token={{token}}&indicator_id={{location_id}}
Get indicator data for a specific breakout indicator:
GET https://api.sparkmap.org/indicator/v1/data.csv?token={{token}}&breakout_id={{breakout_id}}
Get all indicator data for a state:
GET https://api.sparkmap.org/indicator/v1/data.csv?token={{token}}&state={{state}}
If a single indicator is requested, the response is a text string formatted as CSV output. Otherwise, a ZIP file containing multiple compressed CSV files is returned.
Example response for a single indicator:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Location Id,Location Name,Age 0-4,Age 5-17,Age 18-24,Age 25-34,Age 35-44,Age 45-54,Age 55-64,Age 65+
29001,"Adair County, MO",1320,3408,7105,2753,2058,2407,2662,3656
29003,"Andrew County, MO",995,3040,1269,1949,2095,2297,2579,3279
29005,"Atchison County, MO",258,752,315,549,548,697,783,1327
Possible errors:
| Error code | Description |
|---|---|
| 401 Unauthorized | The token is invalid or has expired |
| 400 Bad Request | The inputs supplied to the API are invalid |
| 404 Not Found | No indicators or location items are found for the request |
3.3. Indicator info
Get descriptive information about the indicators accessible by your token.
The request to fetch location types may have the following parameters:
| Parameter | Type | Required? | Description |
|---|---|---|---|
token |
string | required | The access token you received. |
indicator_id |
int | optional | The unique identifier of an indicator. If omitted, the resource returns info for all indicators. |
Two response options are provided: JSON and Comma Separated Values (CSV).
3.3.1. JSON response
Get indicator information in JSON format:
GET https://api.sparkmap.org/indicator/v1/indicators?token={{token}}
The response is a list of indicator info objects.
Example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"indicator_id": 700,
"name": "Total Population",
"category": "Demographics",
"attributes": [
"Total Population",
"Total Land Area (Square Miles)",
"Population Density (Per Square Mile)"
],
"location_key": [
"county",
"state",
"us"
]
"description": "This indicator reports total population and the population density. Population density is defined as the number of persons per square mile.",
"source": "US Census Bureau, <a href=\"https://www.census.gov/programs-surveys/acs/\">American Community Survey</a>.",
"source_date": "2015-19"
},
{
"indicator_id": 700,
"breakout_id": 3701,
"name": "Total Population by Gender",
"category": "Demographics",
"attributes": [
"Male",
"Female",
"Male, Percent, %",
"Female, Percent, %"
],
"location_key": [
"county",
"state",
"us"
]
"description": "This indicator reports the total population of the report area by gender.",
"source": "US Census Bureau, <a href=\"https://www.census.gov/programs-surveys/acs/\">American Community Survey</a>.",
"source_date": "2015-19"
}]
Where an indicator info object is:
| Field | Type | Description |
|---|---|---|
| indicator_id | int | A unique identifer for the indicator |
| breakout_id | int | A unique identifer for the indicator if this is a supplemental breakout indicator |
| name | string | Name of the indicator |
| category | string | Category for the indicator |
| attributes | list | A list of attributes of the indicator |
| location_key | list | A list of location keys indicating location types that the indicator has data for |
| description | string | A description about the indicator or breakout. |
| source | string | Data source for the indicator |
| source_date | string | Source date for the indicator data |
Possible errors:
| Error code | Description |
|---|---|
| 401 Unauthorized | The token is invalid or has expired |
3.3.2 CSV response
Get indicator information in CSV format:
GET https://api.sparkmap.org/indicator/v1/indicators.csv?token={{token}}
The response is a text string formatted as CSV output, with the list of location_key as separate columns and cell value of X indicating data is available for the location type.
Example response:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
indicator_id,breakout_id,name,category,attributes,county,state,us,description,source,source_date
700,,Total Population,Demographics,Total Population; Total Land Area(Square Miles); Population Density (Per Square Mile),X,X,X,"US Census Bureau, <a href=""https://www.census.gov/programs-surveys/acs/"">American Community Survey</a>.",2015-19
700,3702,Total Population by Gender,Demographics,"Male; Female; Male, Percent, %; Female, Percent, %",X,X,X,"This indicator reports the total population of the report area by gender. ","US Census Bureau, <a href=""https://www.census.gov/programs-surveys/acs/"">American Community Survey</a>.",2015-19
Possible errors:
| Error code | Description |
|---|---|
| 401 Unauthorized | The token is invalid or has expired |
Testing
We provide a Swagger-based API testing tool: https://api.sparkmap.org/indicator/swagger/index.html.
Contact Us
Have questions or need support on the API? Send us an email at help@cares.missouri.edu, and we’ll get back to you as quickly as we can.
For more information about us and our products and services, please visit Center for Applied Research and Engagement System at the University of Missouri.