Bureau of Consular Affairs Discovery API

openapi: 3.1.0
info:
  title: CA Data Catalog (CKAN) Datastore Discovery API
  description: 'Best-effort OpenAPI 3.1 description of the Bureau of Consular Affairs (CA) Data Catalog

    API. The catalog runs on the standard CKAN platform, which exposes its functionality at

    `/api/3/action/{action_name}` using both GET and POST. CKAN actions are described in the

    CKAN Action API documentation.


    All CA Data Catalog actions are publicly readable; write actions require an `Authorization`

    header carrying a CKAN API token (obtained from the CKAN user profile).

    '
  version: '3.0'
  contact:
    name: Bureau of Consular Affairs
    url: https://cadatacatalog.state.gov/dataset/
  license:
    name: U.S. Government Work
    url: https://www.usa.gov/government-works
servers:
- url: https://cadatacatalog.state.gov/api/3
  description: CA Data Catalog CKAN Action API
tags:
- name: Discovery
  description: Read-only discovery actions (packages, groups, organizations, tags).
paths:
  /action/site_read:
    get:
      tags:
      - Discovery
      summary: Check whether the site is readable
      operationId: siteRead
      responses:
        '200':
          description: Site readable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessBoolean'
  /action/package_list:
    get:
      tags:
      - Discovery
      summary: List all dataset (package) names
      operationId: packageList
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
      - name: offset
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: List of dataset names
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResult'
  /action/current_package_list_with_resources:
    get:
      tags:
      - Discovery
      summary: List datasets along with their resources
      operationId: currentPackageListWithResources
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
      - name: offset
        in: query
        schema:
          type: integer
      - name: page
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Datasets with resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackagesResult'
  /action/package_show:
    get:
      tags:
      - Discovery
      summary: Retrieve a single dataset (package) by id or name
      operationId: packageShow
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      - name: use_default_schema
        in: query
        schema:
          type: boolean
      - name: include_tracking
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Dataset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageResult'
  /action/package_search:
    get:
      tags:
      - Discovery
      summary: Search datasets with Solr query syntax
      operationId: packageSearch
      parameters:
      - name: q
        in: query
        schema:
          type: string
      - name: fq
        in: query
        schema:
          type: string
      - name: sort
        in: query
        schema:
          type: string
      - name: rows
        in: query
        schema:
          type: integer
      - name: start
        in: query
        schema:
          type: integer
      - name: facet.field
        in: query
        schema:
          type: string
      - name: include_drafts
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
  /action/resource_show:
    get:
      tags:
      - Discovery
      summary: Retrieve a single resource by id
      operationId: resourceShow
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResult'
  /action/resource_search:
    get:
      tags:
      - Discovery
      summary: Search resources within a dataset
      operationId: resourceSearch
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
      - name: fields
        in: query
        schema:
          type: string
      - name: order_by
        in: query
        schema:
          type: string
      - name: offset
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Resource search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
  /action/group_list:
    get:
      tags:
      - Discovery
      summary: List dataset groups
      operationId: groupList
      parameters:
      - name: all_fields
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResult'
  /action/group_show:
    get:
      tags:
      - Discovery
      summary: Retrieve a single group
      operationId: groupShow
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      - name: include_datasets
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /action/organization_list:
    get:
      tags:
      - Discovery
      summary: List organizations
      operationId: organizationList
      parameters:
      - name: all_fields
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Organizations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResult'
  /action/organization_show:
    get:
      tags:
      - Discovery
      summary: Retrieve a single organization
      operationId: organizationShow
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      - name: include_datasets
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
  /action/tag_list:
    get:
      tags:
      - Discovery
      summary: List tags
      operationId: tagList
      parameters:
      - name: query
        in: query
        schema:
          type: string
      - name: vocabulary_id
        in: query
        schema:
          type: string
      - name: all_fields
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Tags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResult'
  /action/tag_show:
    get:
      tags:
      - Discovery
      summary: Retrieve a single tag
      operationId: tagShow
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
      - name: include_datasets
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Tag
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
components:
  schemas:
    Result:
      type: object
      properties:
        help:
          type: string
        success:
          type: boolean
        result:
          type: object
          additionalProperties: true
    PackageResult:
      type: object
      properties:
        help:
          type: string
        success:
          type: boolean
        result:
          $ref: '#/components/schemas/Package'
    SuccessBoolean:
      type: object
      properties:
        help:
          type: string
        success:
          type: boolean
        result:
          type: boolean
    PackagesResult:
      type: object
      properties:
        help:
          type: string
        success:
          type: boolean
        result:
          type: array
          items:
            $ref: '#/components/schemas/Package'
    Resource:
      type: object
      properties:
        id:
          type: string
        package_id:
          type: string
        name:
          type: string
        description:
          type: string
        format:
          type: string
        url:
          type: string
        mimetype:
          type: string
        size:
          type: integer
        created:
          type: string
          format: date-time
        last_modified:
          type: string
          format: date-time
        datastore_active:
          type: boolean
        state:
          type: string
    SearchResult:
      type: object
      properties:
        help:
          type: string
        success:
          type: boolean
        result:
          type: object
          properties:
            count:
              type: integer
            results:
              type: array
              items:
                type: object
                additionalProperties: true
            facets:
              type: object
              additionalProperties: true
            sort:
              type: string
    Package:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        title:
          type: string
        notes:
          type: string
        author:
          type: string
        author_email:
          type: string
        maintainer:
          type: string
        maintainer_email:
          type: string
        license_id:
          type: string
        owner_org:
          type: string
        state:
          type: string
        type:
          type: string
        metadata_created:
          type: string
          format: date-time
        metadata_modified:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              display_name:
                type: string
        groups:
          type: array
          items:
            type: object
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        extras:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
    ResourceResult:
      type: object
      properties:
        help:
          type: string
        success:
          type: boolean
        result:
          $ref: '#/components/schemas/Resource'
    ListResult:
      type: object
      properties:
        help:
          type: string
        success:
          type: boolean
        result:
          type: array
          items: {}
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: Authorization
      description: CKAN API token, generated from the CKAN user profile.