nhgis.yml

openapi: "3.0.0"
info:
  version: "v2"
  title: IPUMS API for NHGIS
servers:
  - url: https://api.ipums.org
security:
  - APIKeyHeader: []
paths:
  /metadata/nhgis/data_tables:
    get:
      summary: List all data_tables
      parameters:
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
        - in: query
          name: pageNumber
          schema:
            type: integer
          required: false
          description: The page number.
        - in: query
          name: pageSize
          schema:
            type: integer
          required: false
          description: The number of records to return per page.
      responses:
        '200':
          description: An array of data_tables
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataTableFull"
  /metadata/nhgis/datasets:
    get:
      summary: List all datasets
      parameters:
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
        - in: query
          name: pageNumber
          schema:
            type: integer
          required: false
          description: The page number.
        - in: query
          name: pageSize
          schema:
            type: integer
          required: false
          description: The number of records to return per page.
      responses:
        '200':
          description: An array of datasets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Datasets"
              example: [
                {
                "name": "1790_cPop",
                "description": "1790 Census: Population Data [US, States & Counties"
              }]
  /metadata/nhgis/datasets/{dataset}:
    get:
      summary: Detailed dataset view
      parameters:
        - in: path
          name: dataset
          schema:
            type: string
          required: true
          description: The name of the dataset.
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
      responses:
        '200':
          description: A dataset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DatasetFull"
  /metadata/nhgis/datasets/{dataset}/data_tables/{dataTable}:
    get:
      summary: Detailed data table view
      parameters:
        - in: path
          name: dataset
          schema:
            type: string
          required: true
          description: The name of the dataset.
        - in: path
          name: dataTable
          schema:
            type: string
          required: true
          description: The name of the data table.
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
      responses:
        '200':
          description: A data table
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataTableFull"
  /metadata/nhgis/time_series_tables:
    get:
      summary: List all time series tables
      parameters:
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
        - in: query
          name: pageNumber
          schema:
            type: integer
          required: false
          description: The page number.
        - in: query
          name: pageSize
          schema:
            type: integer
          required: false
          description: The number of records to return per page.
      responses:
        '200':
          description: An array of time series tables
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TimeSeriesTableSimple"
  /metadata/nhgis/time_series_tables/{timeSeriesTable}:
    get:
      summary: Detailed time series table view
      parameters:
        - in: path
          name: timeSeriesTable
          schema:
            type: string
          required: true
          description: The name of the time series table.
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
      responses:
        '200':
          description: A time series table
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TimeSeriesTableFull"
  /metadata/nhgis/shapefiles:
    get:
      summary: List all the shapefiles.
      parameters:
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
        - in: query
          name: pageNumber
          schema:
            type: integer
          required: false
          description: The page number.
        - in: query
          name: pageSize
          schema:
            type: integer
          required: false
          description: The number of records to return per page.
      responses:
        '200':
          description: An array of shapefiles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Shapefile"
              example: [{
                "name": "base.tl2000.nongen.us_state_1790",
                "year": "1790",
                "geographicLevel": "state",
                "extent": "united states",
                "basis": "2000 tiger/line +",
                "sequence": 1
                }
              ]
  /extracts/{extractNumber}:
    get:
      summary: Get a specific data extract.
      parameters:
        - in: path
          name: extractNumber
          schema:
            type: integer
          required: true
          description: Number of extract to get.
        - in: query
          name: collection
          schema:
            type: string
          required: true
          description: The data collection. This parameter was previously called "product". Using "product" as an alias for "collection" is still valid but may be deprecated in a future version of the API.
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
      responses:
        '200':
          description: A data extract.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataExtract"
  /extracts:
    get:
      summary: Get a list of recent data extracts.
      parameters:
        - in: query
          name: collection
          schema:
            type: string
          required: true
          description: The data collection. This parameter was previously called "product". Using "product" as an alias for "collection" is still valid but may be deprecated in a future version of the API.
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
        - in: query
          name: pageNumber
          schema:
            type: integer
          required: false
          description: The page number.
        - in: query
          name: pageSize
          schema:
            type: integer
          required: false
          description: The number of records to return per page.
      responses:
        '200':
          description: An array of data extracts.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataExtracts"
    post:
      summary: Create a data extract
      parameters:
        - in: query
          name: collection
          schema:
            type: string
          required: true
          description: The data collection. This parameter was previously called "product". Using "product" as an alias for "collection" is still valid but may be deprecated in a future version of the API.
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: The api version.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DataExtractPost"
      responses:
        '200':
          description: Created data extract
          content:
            application/json:

              schema:
                $ref: "#/components/schemas/DataExtractPostResponse"
components:
  schemas:
    TimeSeriesTableFull:
      example: {
        "name": "A00",
        "description": "Total Population",
        "geographicIntegration": "Nominal",
        "sequence": 0.01,
        "timeSeries": [
            {
                "name": "AA",
                "description": "Persons: Total",
                "sequence": 1
            }
        ],
        "geogLevels": [
            {
                "name": "state",
                "description": "State",
                "sequence": 4
            },
            {
                "name": "county",
                "description": "State--County",
                "sequence": 25
            }
        ]}
      properties:
        name:
          type: string
        description:
          type: string
        geographicIntegration:
          type: string
        sequence:
          type: float
        timeSeries:
          type: array
          items:
            properties:
              name:
                type: string
              description:
                type: string
              sequence:
                type: integer
        geogLevels:
          type: array
          items:
            properties:
              name:
                type: string
              description:
                type: string
              sequence:
                type: integer
    TimeSeriesTableSimple:
      example: {
        "name": "A00",
        "description": "Total Population",
        "geographicIntegration": "Nominal",
        "sequence": 0.01,
        "years": [
            "1790",
            "1800",
            "1810",
            "1820",
            "1830",
            "1840",
            "1850",
            "1860",
            "1870",
            "1880",
            "1890",
            "1900",
            "1910",
            "1920",
            "1930",
            "1940",
            "1950",
            "1960",
            "1970",
            "1980",
            "1990",
            "2000",
            "2010"
        ],
        "geogLevels": [
            "state",
            "county"
        ]
        }
      properties:
        name:
          type: string
        description:
          type: string
        geographicIntegration:
          type: string
        sequence:
          type: float
        timeSeries:
          type: array
          items:
            type: string
        geogLevels:
          type: array
          items:
            type: string
    DataTableFull:
      example: {
        "name": "NT1",
        "description": "Total Population",
        "universe": "Persons",
        "nhgisCode": "AAA",
        "sequence": 1,
        "datasetName": "1790_cPop",
        "variables": [ {"description": "Total", "nhgisCode": "AAA001" } ]
        }
      properties:
        name:
          type: string
        nhgisCode:
          type: string
        description:
          type: string
        universe:
          type: string
        sequence:
          type: integer
        datasetName:
          type: string
        variables:
          type: array
          items:
            properties:
              name:
                type: string
              nhgisCode:
                type: string
    DataTableSimple:
      example: {
        "name": "NT1",
        "nhgisCode": "AAA",
        "description": "Total Population",
        "sequence": 1
        }
      properties:
        name:
          type: string
        nhgisCode:
          type: string
        description:
          type: string
        sequence:
          type: integer
    DatasetFull:
      example: {
      "name": "2010_SF1a",
      "group": "2010 Census",
      "description": "SF 1a - P & H Tables [Blocks & Larger Areas]",
      "sequence": 4802,
      "hasMultipleDataTypes": false,
      "dataTables": [
        {
            "name": "P1",
            "nhgisCode": "H7V",
            "description": "Total Population",
            "sequence": 1
        }
       ],
       "geogLevels": [
        {
            "name": "nation",
            "description": "Nation",
            "hasGeogExtentSelection": false,
            "sequence": 1
        }
       ],
       "geographicInstances": [
        {
            "name": "010",
            "description": "Alabama"
        }
       ],
       "breakdowns": [
        {
            "name": "bs32",
            "type": "Spatial",
            "description": "Geographic Subarea (2010 Census and American Community Survey)",
            "breakdownValues": [
                {
                    "name": "bs32.ge00",
                    "description": "Total area"
                }
             ]
        }
        ]
      }
      properties:
        name:
          type: string
        description:
          type: string
        group:
          type: string
        sequence:
          type: integer
        dataTables:
          type: array
          items:
            $ref: "#/components/schemas/DataTableSimple"
        geogLevels:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              hasGeogExtentSelection:
                type: boolean
        hasMultipleDataTypes:
          type: boolean
        breakdowns:
          type: object
          properties:
            name:
              type: string
            type:
              type: string
            description:
              type: string
            breakdownValues:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  description:
                    type: string
            years:
              type: array
              items:
                type: string
            geographicInstances:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  description:
                    type: string
    DatasetSimple:
      example: {
        "name": "1790_cPop",
        "description": "1790 Census: Population Data [US, States & Counties",
        "group": "1790 Census",
        "sequence": 101
        }
      properties:
        name:
          type: string
        description:
          type: string
        group:
          type: string
        sequence:
          type: integer
    Datasets:
      type: array
      items:
        $ref: "#/components/schemas/DatasetSimple"
    Shapefile:
      example:  {
        "name": "base.tl2000.nongen.us_state_1790",
        "year": "1790",
        "geographicLevel": "state",
        "extent": "united states",
        "basis": "2000 tiger/line +",
        "sequence": 1
      }
      properties:
        name:
          type: string
        year:
          type: string
        geographicLevel:
          type: string
        extent:
          type: string
        basis:
          type: integer
        sequence:
          type: integer
    DataExtract: &DataExtract
      example: {
        "extractDefinition": {
          "datasets": {
            "1790_cPop": {"dataTables":[ "NT1" ], "geogLevels":[ "place_00498" ] },
            "1800_cPop": {"dataTables":[ "NT3" ], "geogLevels":[ "state" ] }
          },
          "timeSeriesTables": {
            "A00": { "geogLevels": ["state"] }
          },
          "timeSeriesTableLayout": "time_by_row_layout",
          "dataFormat": "csv_no_header",
          "description": "abc",
          "version": 2,
          "collection": "nhgis"
        },
        "number": 2,
        "status": "complete",
        "downloadLinks": {
          "codebookPreview": "https://api.ipums.org/downloads/nhgis/api/v1/extracts/1234567/nhgis0007_csv_PREVIEW.zip",
          "tableData": "https://api.ipums.org/downloads/nhgis/api/v1/extracts/1234567/nhgis0007_csv.zip",
          "gisData": "https://api.ipums.org/downloads/nhgis/api/v1/extracts/1234567/nhgis0007_shape.zip"
        }
      }
      properties:
        extractDefinition:
          type: object
          properties:
            datasets:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/Dataset"
            timeSeriesTables:
              type: object
              additionalProperties:
                $ref: "#/components/schemas/TimeSeriesTable"
            dataFormat:
              type: string
              enum: [ csv_no_header, csv_header, fixed_width ]
            timeSeriesTableLayout:
              type: string
              enum: [ time_by_column_layout, time_by_row_layout, time_by_file_layout ]
            breakdownAndDataTypeLayout:
              type: string
              enum: [ separate_files, single_file ]
            shapefiles:
              type: array
              items:
                type: string
            geographicExtents:
              type: array
              items:
                type: string
            description:
              type: string
            version:
              type: integer
              format: int32
            collection:
              type: string
        number:
          type: integer
          format: int64
        status:
          type: string
        downloadLinks:
          type: object
          properties:
            codebookPreview:
              type: string
            tableData:
              type: string
            gisData:
              type: string
    DataExtractPost:
      <<: *DataExtract
      example: {
        "datasets": {
          "1790_cPop": {
            "dataTables": [
              "NT1"
            ],
            "geogLevels": [
              "state"
            ]
          }
        },
        "timeSeriesTables": {
          "A00": {
            "geogLevels": [
              "state"
            ],
            "years": [
              "1990"
            ]
          }
        },
        "timeSeriesTableLayout": "time_by_row_layout",
        "dataFormat": "csv_no_header",
        "description": "abc"
      }
      properties:
        datasets:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Dataset"
        timeSeriesTables:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/TimeSeriesTable"
        dataFormat:
          type: string
          enum: [csv_no_header, csv_header, fixed_width]
        timeSeriesTableLayout:
          type: string
          enum: [time_by_column_layout, time_by_row_layout, time_by_file_layout]
        breakdownAndDataTypeLayout:
          type: string
          enum: [separate_files, single_file]
        shapefiles:
          type: array
          items:
            type: string
        geographicExtents:
          type: array
          items:
            type: string
        description:
          type: string
    DataExtractPostResponse:
      <<: *DataExtract
      example: {
        "number": 90,
        "status": "queued",
        "downloadLinks": {},
        "extractDefinition": {
          "dataFormat": "csv_no_header",
          "description": "abc",
          "datasets": {
            "1790_cPop": {
              "dataTables": [
                "NT1"
              ],
              "geogLevels": [
                "state"
              ]
            }
          },
          "timeSeriesTables": {
            "A00": {
              "geogLevels": [
                "state"
              ],
              "years": [
                "1990"
              ]
            }
          },
          "timeSeriesTableLayout": "time_by_row_layout",
          "version": 2,
          "collection": "nhgis"
        },
        "errors": {}
      }
    DataExtracts:
      type: array
      items:
        $ref: "#/components/schemas/DataExtract"
    Dataset:
      type: object
      required:
        - geogLevels
        - dataTables
      properties:
        dataTables:
          type: array
          items:
            type: string
        geogLevels:
          type: array
          items:
            type: string
        breakdownValues:
          type: array
          items:
            type: string
        years:
          type: array
          items:
            type: string
    TimeSeriesTable:
      type: object
      required:
        - geogLevels
      properties:
        geogLevels:
          type: array
          items:
            type: string
        years:
          type: array
          items:
            type: string
    Error:
      required:
        - type
        - status
        - detail
      properties:
        type:
          type: integer
          format: int32
        status:
          type: string
        detail:
          type: string
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization