openapi: 3.1.0
info:
  title: AmeriCorps Open Data API
  version: "1.0.0"
  description: |
    AmeriCorps publishes research, evaluation, and program data through its open
    data portal at https://data.americorps.gov, which is built on the Socrata
    Open Data (SODA) platform. Datasets are accessible programmatically through
    the standard Socrata views and resource endpoints.

    Each dataset is identified by a four-by-four (`xxxx-xxxx`) identifier and can
    be queried via the `/resource/{dataset_id}.{format}` endpoint using SoQL
    (Socrata Query Language) parameters such as `$select`, `$where`, `$order`,
    `$limit`, and `$offset`.
  contact:
    name: AmeriCorps Open Data
    url: https://data.americorps.gov
servers:
  - url: https://data.americorps.gov
    description: AmeriCorps Open Data portal (Socrata)
tags:
  - name: Catalog
    description: Discover datasets published on the AmeriCorps open data portal.
  - name: Datasets
    description: Retrieve dataset rows via the Socrata SODA resource endpoint.
  - name: Metadata
    description: Retrieve dataset metadata and schema information.
paths:
  /api/views:
    get:
      tags:
        - Catalog
      summary: List datasets and assets
      description: |
        Returns a JSON list of all datasets, views, charts, and assets published
        on the AmeriCorps open data portal. Useful for discovery and for
        retrieving dataset identifiers (`id`) needed to call `/resource/{id}`.
      operationId: listViews
      parameters:
        - name: limit
          in: query
          description: Maximum number of assets to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
        - name: page
          in: query
          description: Page number for paginated catalog responses.
          required: false
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Array of dataset/view metadata records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/View"
  /api/views/{dataset_id}.json:
    get:
      tags:
        - Metadata
      summary: Get dataset metadata
      description: |
        Returns the metadata record for a single dataset, including its columns,
        description, tags, and update cadence.
      operationId: getViewMetadata
      parameters:
        - $ref: "#/components/parameters/DatasetId"
      responses:
        "200":
          description: Dataset metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/View"
        "404":
          description: Dataset not found.
  /resource/{dataset_id}.json:
    get:
      tags:
        - Datasets
      summary: Query a dataset (JSON)
      description: |
        Returns rows from the specified dataset as JSON. Supports the Socrata
        SODA SoQL query parameters (`$select`, `$where`, `$order`, `$group`,
        `$limit`, `$offset`, `$q`).
      operationId: getDatasetJson
      parameters:
        - $ref: "#/components/parameters/DatasetId"
        - $ref: "#/components/parameters/SoqlSelect"
        - $ref: "#/components/parameters/SoqlWhere"
        - $ref: "#/components/parameters/SoqlOrder"
        - $ref: "#/components/parameters/SoqlGroup"
        - $ref: "#/components/parameters/SoqlLimit"
        - $ref: "#/components/parameters/SoqlOffset"
        - $ref: "#/components/parameters/SoqlQ"
      responses:
        "200":
          description: Array of dataset rows.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        "400":
          description: Invalid SoQL query.
        "404":
          description: Dataset not found.
  /resource/{dataset_id}.csv:
    get:
      tags:
        - Datasets
      summary: Query a dataset (CSV)
      description: Returns rows from the specified dataset as CSV.
      operationId: getDatasetCsv
      parameters:
        - $ref: "#/components/parameters/DatasetId"
        - $ref: "#/components/parameters/SoqlSelect"
        - $ref: "#/components/parameters/SoqlWhere"
        - $ref: "#/components/parameters/SoqlOrder"
        - $ref: "#/components/parameters/SoqlLimit"
        - $ref: "#/components/parameters/SoqlOffset"
      responses:
        "200":
          description: CSV-formatted dataset rows.
          content:
            text/csv:
              schema:
                type: string
components:
  parameters:
    DatasetId:
      name: dataset_id
      in: path
      required: true
      description: Socrata four-by-four dataset identifier (e.g. `bkv2-68b9`).
      schema:
        type: string
        pattern: "^[a-z0-9]{4}-[a-z0-9]{4}$"
    SoqlSelect:
      name: $select
      in: query
      required: false
      description: SoQL `$select` clause specifying which columns to return.
      schema:
        type: string
    SoqlWhere:
      name: $where
      in: query
      required: false
      description: SoQL `$where` filter clause.
      schema:
        type: string
    SoqlOrder:
      name: $order
      in: query
      required: false
      description: SoQL `$order` clause for sorting results.
      schema:
        type: string
    SoqlGroup:
      name: $group
      in: query
      required: false
      description: SoQL `$group` clause for aggregations.
      schema:
        type: string
    SoqlLimit:
      name: $limit
      in: query
      required: false
      description: Maximum number of rows to return (default 1000, max 50000).
      schema:
        type: integer
        minimum: 1
        maximum: 50000
    SoqlOffset:
      name: $offset
      in: query
      required: false
      description: Row offset for paginating results.
      schema:
        type: integer
        minimum: 0
    SoqlQ:
      name: $q
      in: query
      required: false
      description: Full-text search query.
      schema:
        type: string
  securitySchemes:
    SocrataAppToken:
      type: apiKey
      in: header
      name: X-App-Token
      description: |
        Optional Socrata application token. Anonymous access is allowed, but
        requests without a token are subject to lower throttling limits.
  schemas:
    View:
      type: object
      description: Socrata view/dataset metadata record.
      properties:
        id:
          type: string
          description: Socrata four-by-four dataset identifier.
        name:
          type: string
        description:
          type: string
        category:
          type: string
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: integer
          description: Unix timestamp of creation.
        rowsUpdatedAt:
          type: integer
          description: Unix timestamp of last data update.
        viewCount:
          type: integer
        downloadCount:
          type: integer
        columns:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
security:
  - {}
  - SocrataAppToken: []