opendatanetwork-apiary.apib

FORMAT: 1A
HOST: http://api.opendatanetwork.com/

# ODN API

The Socrata OpenDataNetwork (ODN) REST API exposes public data, often continuosly updated and enhanced, from many thousands of public
government and non profit agencies.

Much of this data originating from independent sources is fused together to create new, and often
powerful, entity level data. The API, in addition to search and autosuggest capabilities for finding datasets,
enables data based comparisons across geographical regions such as states, counties, metropolitan areas,
cities and zip codes using highly vetted data providers such as US Census, BEA, HUD and others. Comparison data
is preformatted for easy and efficient display on a chart, graph or interactive map.

The API also exposes data organized by narrative style questions a human might ask. The questions can
be rapidly found using an autosuggest style index, and then used to directly access all data needed to
thoroughly and authoritatively answer the question. Retrieved data includes time series (temporally aligned),
tabular, map heavy (includes spatial boundaries), and auto generated unstructured descriptive text.

The ODN API does not duplicate API endpoints or services provided by public sector agencies, but rather,
returns context relevant pre-populated REST URLs, when appropriate, so the caller can access data
directly from the source.

The [open source](http://github.com/socrata/odn-backend) API powers [OpenDataNetwork.com](http://OpenDataNetwork.com), an [open source](http://github.com/socrata/opendatanetwork.com)
site; the site highlights myriad uses and provides API badges with contextually relevant API example
REST endpoints and documentation pointers.

Finally, we continuously add new dat sources which appear automatically in the API, so if your favorite data
source is not available, check back soon. You can also join us [HERE](http://www.opendatanetwork.com/join-open-data-network)
and receive updates or let us know which data sources you are most interested in.

## App Tokens

Registering for and including a [Socrata application token](https://dev.socrata.com/docs/app-tokens.html)
is _required_ for the ODN API. They can be passed either using the `app_token` parameter
or the `X-App-Token` HTTP header.

## Suggestions [/suggest/v1/{type}{?query}{?limit}{?app_token}{?variable_id}]

Suggests entities like geographical regions, questions, datasets, publishers and categories
that match the given query prefix or full phrase. Useful for building autosuggest style query
interaction where suggestions are provided as a user types.

+ Parameters
    + type (required, string, `entity`)

        Type of the object to find.

        + Values
            + `entity`
            + `category`
            + `publisher`
            + `dataset`
            + `question`

    + query (required, string, `seattl`)

        Query to match.

    + limit (optional, number)

        Maximum number of results to return.
        Must be an integer from 0 to 100.

        + Default: `5`

    + variable_id (optional, string, `demographics.population.count`)

        This parameter is only available when suggesting entities with `type=entity`.
        If it is provided, suggestions will be filtered to include
        only entities that have data for the given variable.

        If the variable provided is invalid, no entities will be returned.

        Note that this filtering will increase response time significantly,
        so it should only be used when necessary.

    + app_token (optional, string, `cQovpGcdUT1CSzgYk0KPYdAI0`)

        The [Socrata App Token](https://dev.socrata.com/docs/app-tokens.html) to be
        used with your request. The `app_token` parameter is required if an app token is not passed via the `X-App-Token` HTTP header. Clients must [register for their own app tokens](https://dev.socrata.com/docs/app-tokens.html).

### Get suggestions [GET]

+ Request

    Suggest entities that match "seattl".

    - Parameters
        - type: entity
        - query: seattl

    - Headers

            X-App-Token: cQovpGcdUT1CSzgYk0KPYdAI0

+ Response 200 (application/json)

        {
            "options": [
                {
                    "id": "310M200US42660",
                    "name": "Seattle Metro Area (WA)",
                    "type": "regions.msa"
                },
                {
                    "id": "1600000US5363000",
                    "name": "Seattle, WA",
                    "type": "regions.place"
                }
            ]
        }


## Search Datasets [/search/v1/dataset{?entity_id}{?dataset_id}{?limit}{?offset}{?app_token}]

Search for datasets related to an ODN dataset or set of entities.

+ Parameters

    + entity_id (optional, string, `0100000US`)

        Entities to use in formulating the query.

    + dataset_id (optional, string, `demographics.population`)

        If included, the search terms of the dataset
        will be used in the query.

    + limit (optional, number)

        Maximum number of results to return.
        Must be an integer from 0 to 50000.

        + Default: `10`

    + offset (optional, number)

        Number of results to skip.
        Used for pagination.

        + Default: `0`

    + app_token (optional, string, `cQovpGcdUT1CSzgYk0KPYdAI0`)

        The [Socrata App Token](https://dev.socrata.com/docs/app-tokens.html) to be
        used with your request. The `app_token` parameter is required if an app token is not passed via the `X-App-Token` HTTP header. Clients must [register for their own app tokens](https://dev.socrata.com/docs/app-tokens.html).

### Get datasets [GET]

+ Request

    Search for datasets about health and Seattle.

    - Parameters
        - dataset_id: health.health
        - entity_id: 1600000US5363000

    - Headers

            X-App-Token: cQovpGcdUT1CSzgYk0KPYdAI0

+ Response 200 (application/json)


        {
          "datasets":[
            {
              "name":"Big Cities Health Data Inventory",
              "description":"This dataset illustrates health status of 26 of the nation’s largest and most urban cities as captured by 34 health (and six demographics-related) indicators. These indicators represent some of the leading causes of morbidity and mortality in the United States and leading priorities of national, state, and local health agencies. Public health data were captured in nine overarching categories: HIV/AIDS, cancer, nutrition/physical activity/obesity, food safety, infectious disease, maternal and child health, tobacco, injury/violence, and behavioral health/substance abuse.",
              "attribution":"The Big Cities Health Coalition",
              "domain":"bchi.bigcitieshealth.org",
              "domain_url":"http://bchi.bigcitieshealth.org",
              "dataset_url":"https://bchi.bigcitieshealth.org/d/rwyf-6cby",
              "dev_docs_url":"https://dev.socrata.com/foundry/bchi.bigcitieshealth.org/ffnx-yiyc",
              "updated_at":"2016-06-27T19:10:04.000Z",
              "created_at":"2015-09-01T19:23:15.000Z",
              "categories":[
                "education",
                "health"
              ]
            },
            {
              "name":"King County Health Reform Indicators",
              "description":"Health reporting area (HRA) and zip code-level indicators for monitoring the impact of the Affordable Care Act in King County, WA. Topic areas range from access to care to population health. Imported to Socrata to allow data to be pulled as JSON from SODA to feed into Leaflet.js-based maps on an external site.",
              "attribution":"Public Health - Seattle & King County",
              "domain":"data.kingcounty.gov",
              "domain_url":"http://data.kingcounty.gov",
              "dataset_url":"https://data.kingcounty.gov/d/ajpg-dges",
              "dev_docs_url":"https://dev.socrata.com/foundry/data.kingcounty.gov/t34p-gkbv",
              "updated_at":"2014-12-17T00:09:12.000Z",
              "created_at":"2014-03-06T23:17:51.000Z",
              "categories":[
                "health"
              ]
            }
          ]
        }

## Search Questions [/search/v1/question{?query}{?limit}{?offset}{?app_token}]

Search for questions related to the given query using full text search.

+ Parameters

    + query (required, string, `seattle`)

        String to search against.

    + limit (optional, number)

        Maximum number of results to return.
        Must be an integer from 0 to 50000.

        + Default: `10`

    + offset (optional, number)

        Number of results to skip.
        Used for pagination.

        + Default: `0`

    + app_token (optional, string, `cQovpGcdUT1CSzgYk0KPYdAI0`)

        The [Socrata App Token](https://dev.socrata.com/docs/app-tokens.html) to be
        used with your request. The `app_token` parameter is required if an app token is not passed via the `X-App-Token` HTTP header. Clients must [register for their own app tokens](https://dev.socrata.com/docs/app-tokens.html).

### Get questions [GET]

+ Request

    Search for questions about "seattle".

    - Parameters
        - query: seattle

    - Headers

            X-App-Token: cQovpGcdUT1CSzgYk0KPYdAI0

+ Response 200 (application/json)

        {
            "questions":[
                {
                    "entity":{
                        "id":"310M200US42660",
                        "name":"Seattle Metro Area (WA)"
                    },
                    "vector":"population",
                    "metric":"population",
                    "variable_name":"population count",
                    "text":"What is the population count of Seattle Metro Area (WA)?"
                },
                {
                    "entity":{
                        "id":"310M200US42660",
                        "name":"Seattle Metro Area (WA)"
                    },
                    "vector":"occupations",
                    "metric":"business_and_finance",
                    "variable_name":"business and finance employment rate",
                    "text":"What is the business and finance employment rate of Seattle Metro Area (WA)?"
                }
            ]
        }

## Entity Lookup [/entity/v1{?entity_id}{?entity_name}{?entity_type}{?app_token}]

Find all entities that match the given constraints.
Useful for looking up the ID of an entity from its name,
or the name of an entity from its ID.

Note that a name may match multiple entities of the same type
and that it is up to the client to decide which one is the best fit.

+ Parameters
    + entity_id (optional, string, `0400000US53`)

        ID of the entity.

    + entity_name (optional, string, `washington`)

        Name of the entity.

    + entity_type (optional, string, `region.state`)

        Type of the entity.

    + app_token (optional, string, `cQovpGcdUT1CSzgYk0KPYdAI0`)

        The [Socrata App Token](https://dev.socrata.com/docs/app-tokens.html) to be
        used with your request. The `app_token` parameter is required if an app token is not passed via the `X-App-Token` HTTP header. Clients must [register for their own app tokens](https://dev.socrata.com/docs/app-tokens.html).


### Get Entities [GET]

+ Request

    Find the ID of Washington state.

    - Parameters
        - entity_name: washington
        - entity_type: region.state

    - Headers

            X-App-Token: cQovpGcdUT1CSzgYk0KPYdAI0

+ Response 200 (application/json)

        {
            "entities": [
                {
                    "id": "0400000US53",
                    "name": "Washington",
                    "type": "region.state"
                }
            ]
        }

## Entity Relationships [/entity/v1/{relation}{?entity_id}{?limit}{?app_token}{?variable_id}]

Find entities that are related to one another.

Region relations are specified in
[`Config.type_relations`](https://github.com/socrata/odn-backend/blob/1d782093dba3e9f98ac9bc7edfac32be915aa81b/app/constants.js#L40).

Entities are grouped by type and sorted in descending order by their rank.
For example, region entities are sorted in descending order by population.

+ Parameters
    + relation (required, string, `parent`)

        The type of relation to find.

        + Values
            + `parent`
            + `child`
            + `sibling`
            + `peer`

    + entity_id (required, string, `0400000US53`)

        ID of the target entity.

    + variable_id (optional, string, `demographics.population.seattle`)

        If this parameter is included, only entities with data for the given
        variable will be returned. Note that this may cause the number of
        entities returned to be less than the specified `limit`.

    + limit (optional, number)

        Maximum number of entities in each group.
        Must be an integer from 1 to 1000.

        + Default: `10`

    + app_token (optional, string, `cQovpGcdUT1CSzgYk0KPYdAI0`)

        The [Socrata App Token](https://dev.socrata.com/docs/app-tokens.html) to be
        used with your request. The `app_token` parameter is required if an app token is not passed via the `X-App-Token` HTTP header. Clients must [register for their own app tokens](https://dev.socrata.com/docs/app-tokens.html).

### Find the relatives of an entity [GET]

+ Request

    Get the parent region of Washington state.

    - Parameters
        - relation: parent
        - entity_id: 0400000US53

    - Headers

            X-App-Token: cQovpGcdUT1CSzgYk0KPYdAI0

+ Response 200 (application/json)

        {
            "relatives": [
                {
                    "type": "region.division",
                    "entities": [
                        {
                            "id": "0300000US9",
                            "name": "Pacific Division",
                            "type": "region.division"
                        }
                    ]
                }
            ]
        }

## Data Availability [/data/v1/availability/{?entity_id}{?app_token}]

Find all of the topics, datasets, and variables that have data
for all of the given entities.

+ Parameters
    + entity_id (required, string, `0100000US,0400000US53`)

        Comma separated list of entity IDs.

    + app_token (optional, string, `cQovpGcdUT1CSzgYk0KPYdAI0`)

        The [Socrata App Token](https://dev.socrata.com/docs/app-tokens.html) to be
        used with your request. The `app_token` parameter is required if an app token is not passed via the `X-App-Token` HTTP header. Clients must [register for their own app tokens](https://dev.socrata.com/docs/app-tokens.html).

### Find all available data for some entities [GET]

+ Request

    Get variables that have data for both the United States and Washington State.

    - Parameters
        - entity_id: 0100000US,0400000US53

    - Headers

            X-App-Token: cQovpGcdUT1CSzgYk0KPYdAI0

+ Response 200 (application/json)

        {
            "topics": {
                "demographics": {
                    "id": "demographics",
                    "name": "Demographics",
                    "datasets": {
                        "population": {
                            "fxf": "9jg8-ki9x",
                            "constraints": [
                                "year"
                            ],
                            "searchTerms": [
                                "population",
                                "household",
                                "demographics",
                                "ethnicity",
                                "minority"
                            ],
                            "sources": [
                                {
                                    "name": "U.S. Census American Community Survey",
                                    "url": "https://www.census.gov/programs-surveys/acs/"
                                }
                            ],
                            "id": "demographics.population",
                            "domain": "odn.data.socrata.com",
                            "description": "",
                            "url": "https://odn.data.socrata.com/resource/9jg8-ki9x.json",
                            "name": "Population",
                            "variables": {
                                "change": {
                                    "name": "Population Change",
                                    "description": "Percent change from the previous year",
                                    "id": "demographics.population.change"
                                },
                                "count": {
                                    "name": "Population Count",
                                    "id": "demographics.population.count"
                                }
                            }
                        }
                    }
                }
            }
        }

## Data Constraints [/data/v1/constraint/{variable}{?entity_id}{?constraint}{?app_token}]

Get constraints for the given variable and entities.

+ Parameters
    + variable (required, string, `demographics.population.count`)

        Full ID of the variable to retrieve.

    + entity_id (required, string, `0100000US,0400000US53`)

        Comma separated list of entity IDs.

    + constraint (required, string, `year`)

        Constraint to use.

    + app_token (optional, string, `cQovpGcdUT1CSzgYk0KPYdAI0`)

        The [Socrata App Token](https://dev.socrata.com/docs/app-tokens.html) to be
        used with your request. The `app_token` parameter is required if an app token is not passed via the `X-App-Token` HTTP header. Clients must [register for their own app tokens](https://dev.socrata.com/docs/app-tokens.html).


### Get constraint permutations for entities [GET]

+ Request

    Get all the years that have population count data for the United States
    and Washington state.

    - Parameters
        - entity_id: 0100000US,0400000US53
        - variable: demographics.population.count
        - constraint: year

    - Headers

            X-App-Token: cQovpGcdUT1CSzgYk0KPYdAI0

+ Response 200 (application/json)

        {
          "permutations": [
            {
              "constraint_value": "2009"
            },
            {
              "constraint_value": "2010"
            },
            {
              "constraint_value": "2011"
            },
            {
              "constraint_value": "2012"
            },
            {
              "constraint_value": "2013"
            }
          ]
        }

## Data Values [/data/v1/values{?variable}{?entity_id}{?forecast}{?describe}{?format}{?app_token}]

Retrieve the values for available data about entities.

To retrieve values for multiple variables, values must be specified
for every constraint in the dataset. For example, to get all of the variables
in the `jobs.occupations` dataset, we would need to specify values
for both `year` and `occupation` by setting passing `year=2013` and
`occupation=Engineering`.

+ Parameters

    + variable (required, string, `demographics.population.count`)

        Comma separated list of variable IDs.
        Defaults to retrieving all variables.
        It is also possible to pass in a topic such as
        `demographics`, or a dataset such as `demographics.population`,
        which would both be equivalent to specifying
        `demographics.population.count` and `demographics.population.change`.
        Note that only variables in the same dataset are allowed.

    + entity_id (optional, string, `0100000US,0400000US53`)

        Comma separated list of entity IDs.
        Defaults to retrieving all entities.
        Note that since there is currently no results pagination,
        retrieving values for all entities may produce incomplete results.

    + forecast (optional, number, `3`)

        Number of steps to forecast.
        Must be an integer between 0 and 20.
        Forecasts are produced using linear extrapolation
        on the data. They are only available when retrieving
        data for a single variable across many numerical
        constraint options.

        + Default `0`

    + describe (optional, boolean, `false`)

        Whether or not to produce a description of the data.
        Set to `true` to produce a description.
        Descriptions are not available if no entities are specified.

        + Default `false`

    + format (optional, string)

        If format is set to `google`, the data frame will be formatted
        as a [Google Visualizations data table](https://developers.google.com/chart/interactive/docs/reference#datatable-class).
        If the format is not provided or invalid, then the frame
        will be formatted normally.

        + Values
            + `google`

    + app_token (optional, string, `cQovpGcdUT1CSzgYk0KPYdAI0`)

        The [Socrata App Token](https://dev.socrata.com/docs/app-tokens.html) to be
        used with your request. The `app_token` parameter is required if an app token is not passed via the `X-App-Token` HTTP header. Clients must [register for their own app tokens](https://dev.socrata.com/docs/app-tokens.html).

### Get values for variables [GET]

+ Request

    Get the annual populations of the United States and Washington and
    forecast 3 years into the future.

    - Parameters
        - entity_id: 0100000US,0400000US53
        - variable: demographics.population.count
        - forecast: 3
        - describe: true

    - Headers

            X-App-Token: cQovpGcdUT1CSzgYk0KPYdAI0

+ Response 200 (application/json)

        {
          "data": [
            [
              "year",
              "0100000US",
              "forecast",
              "0400000US53",
              "forecast"
            ],
            [
              2009,
              301461533,
              false,
              6465755,
              false
            ],
            [
              2010,
              303965272,
              false,
              6561297,
              false
            ],
            [
              2011,
              306603772,
              false,
              6652845,
              false
            ],
            [
              2012,
              309138711,
              false,
              6738714,
              false
            ],
            [
              2013,
              311536594,
              false,
              6819579,
              false
            ],
            [
              2014,
              314055359.25,
              true,
              6908035,
              true
            ],
            [
              2015,
              316574124.5,
              true,
              6996491,
              true
            ],
            [
              2016,
              319092889.75,
              true,
              7084947,
              true
            ]
          ],
          "forecast_info": {
            "algorithm_name": "linear",
            "algorithm_url": "https://en.wikipedia.org/wiki/Extrapolation#Linear_extrapolation"
          }
        }

## Map Creation [/data/v1/map/new{?variable}{?entity_id}{?constraint}{?app_token}]

Create a new map representing the specified geographical entities.
Returns a bounding box containing the given entities geographical boundaries,
summary statistics of the variable across all entities of the same type (e.g.
states, counties, etc.), and a session ID used to efficiently retrieve map
data. Note: session IDs expire after 24 hours.

Map data is transferred using [socket.io](http://socket.io/)
which will use websockets if possible and fall back to HTTP on browsers that
don't support it.

To request map data, send a JSON-formatted message with the following fields:
+ `session_id`: The session ID from when the map was created.
    This is used to keep track of information about the map and avoid
    sending duplicate data.
+ `zoom_level`: An integer specifying the level of detail of the polygons
    of the map where 0 is the least detailed and 18 is the most detailed.
    Using Leaflet's zoom level works well for this.
+ `bounds`: Bounding box of the map in the following order:
    + latitude of NW point
    + longitude of NW point
    + latitude of SE point
    + longitude of SE point

The server will eventually send back a JSON response with the following fields:
+ `type`: Type of the message, which should be `geojson`.
    If the type is `error`, then there was a problem processing the request.
+ `message`: Message which the server is responding to.
+ `geojson`: GeoJSON features with the following properties: `id`, `name`, `type`,
    `value`, and `value_formatted`.

For example, the following message was to render a map around Idaho:

```
{
    "bounds":[
        50.88917404890332,
        -133.35205078125003,
        43.43696596521823,
        -108.32519531250001
    ],
    "zoom_level":6,
    "session_id":"6wb7grag543an42px2bvxtj4i"
}
```

Which received the following response (edited for brevity):

```
{
    "geojson":{
        "type":"FeatureCollection",
        "features":[
            {
                "properties":{
                    "id":"0400000US16",
                    "name":"Idaho",
                    "value":"1583364",
                    "value_formatted":"1,583,364"
                }
            }
        ]
    },
    "message":{
        "bounds":[
            50.88917404890332,
            -133.35205078125003,
            43.43696596521823,
            -108.32519531250001
        ],
        "zoom_level":6,
        "session_id":"6wb7grag543an42px2bvxtj4i"
    },
    "type":"geojson"
}
```

+ Parameters

    + variable (required, string, `demographics.population.count`)

        A single variable ID.

    + entity_id (required, string, `0400000US53,0400000US08`)

        A comma separated list of entity IDs.
        Entities must have the same type and represent geographical regions.

    + constraint (optional, string)

        Values must be specified for each constraint in the dataset.
        For example, to generate map data for `demographics.population.count`,
        you must specify a value for `year` by passing `year=2013`.

    + app_token (optional, string, `cQovpGcdUT1CSzgYk0KPYdAI0`)

        The [Socrata App Token](https://dev.socrata.com/docs/app-tokens.html) to be
        used with your request. The `app_token` parameter is required if an app token is not passed via the `X-App-Token` HTTP header. Clients must [register for their own app tokens](https://dev.socrata.com/docs/app-tokens.html).

### Create a map [GET]

+ Request

    Create a map to show the population of Washington and Colorado in 2013.

    - Parameters
        - variable: demographics.population.count
        - entity_id: region.state
        - year: 2013

    - Headers

            X-App-Token: cQovpGcdUT1CSzgYk0KPYdAI0

+ Response 200 (application/json)

        {
            "session_id": "rhzpyxdvq56cc9cbg3ssb57b9",
            "summary_statistics": {
                "names": ["minimum", "average", "maximum"],
                "values": [570134, 6061914.615384615385, 37659181],
                "values_formatted": ["570,134", "6,061,914", "37,659,181"]
            },
            "bounds": [
                [40.712, -74.227],
                [40.774, -74.125]
            ]
        }