openapi: 3.0.0
servers:
  - url: http://api.opendatanetwork.com
info:
  description: |-
    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.
  title: ODN API
  version: 1.0.0
  x-apisguru-categories:
    - open_data
  x-origin:
    - converter:
        url: https://github.com/mermade/oas-kit
        version: 7.0.4
      format: apiBlueprint
      url: https://raw.githubusercontent.com/socrata/odn-backend/master/opendatanetwork-apiary.apib
      version: 1A
  x-providerName: opendatanetwork.com
tags: []
paths:
  /data/v1/availability/:
    get:
      description: ""
      operationId: Find all available data for some entities
      parameters:
        - description: Comma separated list of entity IDs.
          example: 0100000US,0400000US53
          in: query
          name: entity_id
          required: true
          schema:
            type: string
        - description: |-
            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).
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: query
          name: app_token
          required: false
          schema:
            type: string
        - description: e.g. cQovpGcdUT1CSzgYk0KPYdAI0
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: header
          name: X-App-Token
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    topics:
                      demographics:
                        datasets:
                          population:
                            constraints:
                              - year
                            description: ""
                            domain: odn.data.socrata.com
                            fxf: 9jg8-ki9x
                            id: demographics.population
                            name: Population
                            searchTerms:
                              - population
                              - household
                              - demographics
                              - ethnicity
                              - minority
                            sources:
                              - name: U.S. Census American Community Survey
                                url: https://www.census.gov/programs-surveys/acs/
                            url: https://odn.data.socrata.com/resource/9jg8-ki9x.json
                            variables:
                              change:
                                description: Percent change from the previous year
                                id: demographics.population.change
                                name: Population Change
                              count:
                                id: demographics.population.count
                                name: Population Count
                        id: demographics
                        name: Demographics
          description: OK
          headers: {}
      summary: Find all available data for some entities
      tags: []
  "/data/v1/constraint/{variable}":
    get:
      description: ""
      operationId: Get constraint permutations for entities
      parameters:
        - description: Full ID of the variable to retrieve.
          example: demographics.population.count
          in: path
          name: variable
          required: true
          schema:
            type: string
        - description: Comma separated list of entity IDs.
          example: 0100000US,0400000US53
          in: query
          name: entity_id
          required: true
          schema:
            type: string
        - description: Constraint to use.
          example: year
          in: query
          name: constraint
          required: true
          schema:
            type: string
        - description: |-
            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).
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: query
          name: app_token
          required: false
          schema:
            type: string
        - description: e.g. cQovpGcdUT1CSzgYk0KPYdAI0
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: header
          name: X-App-Token
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    permutations:
                      - constraint_value: "2009"
                      - constraint_value: "2010"
                      - constraint_value: "2011"
                      - constraint_value: "2012"
                      - constraint_value: "2013"
          description: OK
          headers: {}
      summary: Get constraint permutations for entities
      tags: []
  /data/v1/map/new:
    get:
      description: ""
      operationId: Create a map
      parameters:
        - description: A single variable ID.
          example: demographics.population.count
          in: query
          name: variable
          required: true
          schema:
            type: string
        - description: |-
            A comma separated list of entity IDs.
            Entities must have the same type and represent geographical regions.
          example: 0400000US53,0400000US08
          in: query
          name: entity_id
          required: true
          schema:
            type: string
        - description: |-
            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`.
          in: query
          name: constraint
          required: false
          schema:
            type: string
        - description: |-
            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).
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: query
          name: app_token
          required: false
          schema:
            type: string
        - description: e.g. cQovpGcdUT1CSzgYk0KPYdAI0
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: header
          name: X-App-Token
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    bounds:
                      - - 40.712
                        - -74.227
                      - - 40.774
                        - -74.125
                    session_id: rhzpyxdvq56cc9cbg3ssb57b9
                    summary_statistics:
                      names:
                        - minimum
                        - average
                        - maximum
                      values:
                        - 570134
                        - 6061914.615384615
                        - 37659181
                      values_formatted:
                        - 570,134
                        - 6,061,914
                        - 37,659,181
          description: OK
          headers: {}
      summary: Create a map
      tags: []
  /data/v1/values:
    get:
      description: ""
      operationId: Get values for variables
      parameters:
        - description: |-
            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.
          example: demographics.population.count
          in: query
          name: variable
          required: true
          schema:
            type: string
        - description: |-
            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.
          example: 0100000US,0400000US53
          in: query
          name: entity_id
          required: false
          schema:
            type: string
        - description: |-
            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`
          example: "3"
          in: query
          name: forecast
          required: false
          schema:
            type: number
        - description: |-
            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`
          example: "false"
          in: query
          name: describe
          required: false
          schema:
            type: boolean
        - description: |-
            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.
          in: query
          name: format
          required: false
          schema:
            enum:
              - google
            type: string
        - description: |-
            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).
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: query
          name: app_token
          required: false
          schema:
            type: string
        - description: e.g. cQovpGcdUT1CSzgYk0KPYdAI0
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: header
          name: X-App-Token
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    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
          description: OK
          headers: {}
      summary: Get values for variables
      tags: []
  /entity/v1:
    get:
      description: ""
      operationId: Get Entities
      parameters:
        - description: ID of the entity.
          example: 0400000US53
          in: query
          name: entity_id
          required: false
          schema:
            type: string
        - description: Name of the entity.
          example: washington
          in: query
          name: entity_name
          required: false
          schema:
            type: string
        - description: Type of the entity.
          example: region.state
          in: query
          name: entity_type
          required: false
          schema:
            type: string
        - description: |-
            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).
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: query
          name: app_token
          required: false
          schema:
            type: string
        - description: e.g. cQovpGcdUT1CSzgYk0KPYdAI0
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: header
          name: X-App-Token
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    entities:
                      - id: 0400000US53
                        name: Washington
                        type: region.state
          description: OK
          headers: {}
      summary: Get Entities
      tags: []
  "/entity/v1/{relation}":
    get:
      description: ""
      operationId: Find the relatives of an entity
      parameters:
        - description: The type of relation to find.
          example: parent
          in: path
          name: relation
          required: true
          schema:
            enum:
              - parent
              - child
              - sibling
              - peer
            type: string
        - description: ID of the target entity.
          example: 0400000US53
          in: query
          name: entity_id
          required: true
          schema:
            type: string
        - description: |-
            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`.
          example: demographics.population.seattle
          in: query
          name: variable_id
          required: false
          schema:
            type: string
        - description: |-
            Maximum number of entities in each group.
            Must be an integer from 1 to 1000.
          in: query
          name: limit
          required: false
          schema:
            default: 10
            type: number
        - description: |-
            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).
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: query
          name: app_token
          required: false
          schema:
            type: string
        - description: e.g. cQovpGcdUT1CSzgYk0KPYdAI0
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: header
          name: X-App-Token
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    relatives:
                      - entities:
                          - id: 0300000US9
                            name: Pacific Division
                            type: region.division
                        type: region.division
          description: OK
          headers: {}
      summary: Find the relatives of an entity
      tags: []
  /search/v1/dataset:
    get:
      description: ""
      operationId: Get datasets
      parameters:
        - description: Entities to use in formulating the query.
          example: 0100000US
          in: query
          name: entity_id
          required: false
          schema:
            type: string
        - description: |-
            If included, the search terms of the dataset
            will be used in the query.
          example: demographics.population
          in: query
          name: dataset_id
          required: false
          schema:
            type: string
        - description: |-
            Maximum number of results to return.
            Must be an integer from 0 to 50000.
          in: query
          name: limit
          required: false
          schema:
            default: 10
            type: number
        - description: |-
            Number of results to skip.
            Used for pagination.
          in: query
          name: offset
          required: false
          schema:
            type: number
        - description: |-
            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).
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: query
          name: app_token
          required: false
          schema:
            type: string
        - description: e.g. cQovpGcdUT1CSzgYk0KPYdAI0
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: header
          name: X-App-Token
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    datasets:
                      - attribution: The Big Cities Health Coalition
                        categories:
                          - education
                          - health
                        created_at: 2015-09-01T19:23:15.000Z
                        dataset_url: https://bchi.bigcitieshealth.org/d/rwyf-6cby
                        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."
                        dev_docs_url: https://dev.socrata.com/foundry/bchi.bigcitieshealth.org/ffnx-yiyc
                        domain: bchi.bigcitieshealth.org
                        domain_url: http://bchi.bigcitieshealth.org
                        name: Big Cities Health Data Inventory
                        updated_at: 2016-06-27T19:10:04.000Z
                      - attribution: Public Health - Seattle & King County
                        categories:
                          - health
                        created_at: 2014-03-06T23:17:51.000Z
                        dataset_url: https://data.kingcounty.gov/d/ajpg-dges
                        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.
                        dev_docs_url: https://dev.socrata.com/foundry/data.kingcounty.gov/t34p-gkbv
                        domain: data.kingcounty.gov
                        domain_url: http://data.kingcounty.gov
                        name: King County Health Reform Indicators
                        updated_at: 2014-12-17T00:09:12.000Z
          description: OK
          headers: {}
      summary: Get datasets
      tags: []
  /search/v1/question:
    get:
      description: ""
      operationId: Get questions
      parameters:
        - description: String to search against.
          example: seattle
          in: query
          name: query
          required: true
          schema:
            type: string
        - description: |-
            Maximum number of results to return.
            Must be an integer from 0 to 50000.
          in: query
          name: limit
          required: false
          schema:
            default: 10
            type: number
        - description: |-
            Number of results to skip.
            Used for pagination.
          in: query
          name: offset
          required: false
          schema:
            type: number
        - description: |-
            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).
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: query
          name: app_token
          required: false
          schema:
            type: string
        - description: e.g. cQovpGcdUT1CSzgYk0KPYdAI0
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: header
          name: X-App-Token
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    questions:
                      - entity:
                          id: 310M200US42660
                          name: Seattle Metro Area (WA)
                        metric: population
                        text: What is the population count of Seattle Metro Area (WA)?
                        variable_name: population count
                        vector: population
                      - entity:
                          id: 310M200US42660
                          name: Seattle Metro Area (WA)
                        metric: business_and_finance
                        text: What is the business and finance employment rate of Seattle Metro Area (WA)?
                        variable_name: business and finance employment rate
                        vector: occupations
          description: OK
          headers: {}
      summary: Get questions
      tags: []
  "/suggest/v1/{type}":
    get:
      description: ""
      operationId: Get suggestions
      parameters:
        - description: Type of the object to find.
          example: entity
          in: path
          name: type
          required: true
          schema:
            enum:
              - entity
              - category
              - publisher
              - dataset
              - question
            type: string
        - description: Query to match.
          example: seattl
          in: query
          name: query
          required: true
          schema:
            type: string
        - description: |-
            Maximum number of results to return.
            Must be an integer from 0 to 100.
          in: query
          name: limit
          required: false
          schema:
            default: 5
            type: number
        - description: |-
            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.
          example: demographics.population.count
          in: query
          name: variable_id
          required: false
          schema:
            type: string
        - description: |-
            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).
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: query
          name: app_token
          required: false
          schema:
            type: string
        - description: e.g. cQovpGcdUT1CSzgYk0KPYdAI0
          example: cQovpGcdUT1CSzgYk0KPYdAI0
          in: header
          name: X-App-Token
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    options:
                      - id: 310M200US42660
                        name: Seattle Metro Area (WA)
                        type: regions.msa
                      - id: 1600000US5363000
                        name: Seattle, WA
                        type: regions.place
          description: OK
          headers: {}
      summary: Get suggestions
      tags: []
components:
  schemas:
    Data_Availability: {}
    Data_Constraints: {}
    Data_Values: {}
    Entity_Lookup: {}
    Entity_Relationships: {}
    Map_Creation: {}
    Search_Datasets: {}
    Search_Questions: {}
    Suggestions: {}
