OpenGov Package API

openapi: 3.2.0
info:
  title: Open Data CKAN Action Package API
  version: '2.9'
  description: "Open Data CKAN's Action API is a powerful, RPC-style API that exposes several features.\n\nDatasets are managed as packages of metadata and resources.\n\nAll endpoints are available under `/api/3/action/<action_name>`.\n\nEndpoints support POST requests with an application/json or a multipart/form-data body.\n  - Use an application/json POST request when nested json parameters are required\n  - Use a multipart/form-data POST request when file uploads are required\n\nRead-only endpoints (`*_show`, `*_list`, `*_search` etc.) accept GET requests with query parameters.\nResponses are returned in a JSON envelope on success:\n```json\n{\n  \"help\": \"url to complete endpoint help\",\n  \"success\": true,\n  \"result\": {...}\n}\n```\nor on errors:\n```json\n{\n  \"help\": \"url to complete endpoint help\",\n  \"success\": false,\n  \"error\": {\n    \"__type\": \"error type\",\n    \"message\": \"error message\",\n    \"field-with-error\": [\"first-error\", \"second-error\"],\n    ...\n  }\n}\n```\n"
  contact:
    name: CKAN Community
    url: https://ckan.org/community
  license:
    name: GNU Affero General Public License (AGPL) v3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: https://cloudcity.ogopendata.com/api/3/action
  description: Cloud City Open Data
tags:
- name: package
  description: On early CKAN versions, datasets were called packages and this name has stuck in some places, specially internally and on API calls. Package has exactly the same meaning as dataset.
paths:
  /package_list:
    get:
      operationId: packageList
      summary: Return a list of the names of the site's datasets (packages).
      tags:
      - package
      responses:
        '200':
          description: Envelope with string array under `result`
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    result:
                      type: array
                      items:
                        type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - ApiTokenAuth: []
  /package_search:
    get:
      operationId: packageSearch
      summary: Searches for datasets (packages) satisfying a given search criteria.
      description: This action accepts solr search query parameters (details below), and returns a dictionary of results, including dictized datasets that match the search criteria, a search count and also facet information.
      tags:
      - package
      parameters:
      - in: query
        name: q
        schema:
          type: string
        description: A solr query string that will be used to filter and score results
        required: false
      - in: query
        name: fq
        schema:
          type: string
        description: A solr filter query that will facet results by removing non-matching items.
        required: false
      - in: query
        name: sort
        schema:
          type: string
        description: Sort order for the search results, defaults to `score desc, metadata_modified desc`.
        required: false
      - in: query
        name: rows
        schema:
          type: integer
          default: 10
          maximum: 1000
        description: The maximum number of results to return
      - in: query
        name: start
        schema:
          type: integer
          default: 0
        description: The offset from the beginning of results for pagination
      - in: query
        name: include_private
        schema:
          type: boolean
          default: false
        description: Include private datasets in the search results. Only private datasets from the user's organizations will be returned. Sysadmins will be returned all private datasets.
      responses:
        '200':
          description: Search results envelope
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    result:
                      type: object
                      properties:
                        count:
                          type: integer
                        results:
                          type: array
                          items:
                            $ref: '#/components/schemas/Dataset'
              examples:
                search_results:
                  summary: Search results
                  value:
                    help: https://demo.ckan.org/api/3/action/help_show?name=package_search
                    success: true
                    result:
                      count: 2
                      results:
                      - id: dataset-1
                        name: dataset-1
                        title: First Dataset
                        notes: Description of first dataset
                        url: https://example.com/dataset1
                        version: '1.0'
                        author: Author One
                        author_email: author1@example.com
                        maintainer: Maintainer One
                        maintainer_email: maintainer1@example.com
                        license_id: cc-by
                        owner_org: org-1
                        private: false
                        state: active
                        resources: []
                        tags: []
                        groups: []
                      - id: dataset-2
                        name: dataset-2
                        title: Second Dataset
                        notes: Description of second dataset
                        url: https://example.com/dataset2
                        version: '2.0'
                        author: Author Two
                        author_email: author2@example.com
                        maintainer: Maintainer Two
                        maintainer_email: maintainer2@example.com
                        license_id: cc-by
                        owner_org: org-2
                        private: false
                        state: active
                        resources: []
                        tags: []
                        groups: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - ApiTokenAuth: []
  /package_show:
    get:
      operationId: packageShow
      summary: Return the metadata of a dataset (package) and its resources.
      tags:
      - package
      parameters:
      - in: query
        name: id
        required: true
        schema:
          type: string
        description: Dataset id or name
      - in: query
        name: use_default_schema
        schema:
          type: boolean
          default: false
      - in: query
        name: include_tracking
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Envelope with dataset object under `result`
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/Dataset'
              examples:
                success:
                  summary: Successful dataset retrieval
                  value:
                    help: https://demo.ckan.org/api/3/action/help_show?name=package_show
                    success: true
                    result:
                      id: test-dataset
                      name: test-dataset
                      title: Test Dataset
                      notes: A test dataset for demonstration
                      url: https://example.com
                      version: '1.0'
                      author: Test Author
                      author_email: test@example.com
                      maintainer: Test Maintainer
                      maintainer_email: maintainer@example.com
                      license_id: cc-by
                      owner_org: test-org
                      private: false
                      state: active
                      resources:
                      - id: resource-1
                        package_id: test-dataset
                        url: https://example.com/data.csv
                        name: Data CSV
                        description: Main data file
                        format: CSV
                        size: 1024
                        mimetype: text/csv
                        created: '2024-01-01T00:00:00Z'
                        last_modified: '2024-01-01T00:00:00Z'
                      tags:
                      - id: tag-1
                        name: test
                        display_name: Test
                        vocabulary_id: ''
                        state: active
                      groups: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - ApiTokenAuth: []
  /package_create:
    post:
      operationId: packageCreate
      summary: Create a new dataset (package).
      description: You must be authorized to create new datasets.
      tags:
      - package
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Dataset'
            examples:
              basic_dataset:
                summary: Basic dataset creation
                value:
                  name: my-new-dataset
                  title: My New Dataset
                  notes: Description of my dataset
                  url: https://example.com
                  version: '1.0'
                  author: John Doe
                  author_email: john@example.com
                  maintainer: Jane Smith
                  maintainer_email: jane@example.com
                  license_id: cc-by
                  owner_org: my-organization
                  private: false
                  resources:
                  - url: https://example.com/data.csv
                    name: Data File
                    description: Main data file
                    format: CSV
                  tags:
                  - name: environment
                  - name: data
      responses:
        '200':
          description: Pacakge create result envelope
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/Dataset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '409':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - ApiTokenAuth: []
  /package_patch:
    post:
      operationId: packagePatch
      summary: Update only specific fields of an existing dataset
      description: Any fields not passed will retain their original values.
      tags:
      - package
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Dataset'
            examples:
              basic_dataset:
                summary: Basic dataset patch
                value:
                  name: my-new-dataset
                  title: My New Dataset
                  notes: Description of my dataset
                  url: https://example.com
                  version: '1.0'
                  author: John Doe
                  author_email: john@example.com
                  maintainer: Jane Smith
                  license_id: cc-by
                  owner_org: my-organization
                  private: false
      responses:
        '200':
          description: Package patch result envelope
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    result:
                      $ref: '#/components/schemas/Dataset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/AuthorizationError'
        '409':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - ApiTokenAuth: []
components:
  schemas:
    Envelope:
      type: object
      required:
      - help
      - success
      properties:
        help:
          type: string
        success:
          type: boolean
        result:
          type: object
          additionalProperties: true
    Resource:
      type: object
      description: CKAN Resource
      additionalProperties: true
      properties:
        id:
          type: string
        package_id:
          type: string
        url:
          type: string
        name:
          type: string
        description:
          type: string
        format:
          type: string
        size:
          type: integer
        mimetype:
          type: string
        hash:
          type: string
        created:
          type: string
          format: date-time
        last_modified:
          type: string
          format: date-time
    Group:
      type: object
      description: CKAN Group
      additionalProperties: true
      properties:
        id:
          type: string
        name:
          type: string
        title:
          type: string
        description:
          type: string
        image_url:
          type: string
        state:
          type: string
        package_count:
          type: integer
    Dataset:
      type: object
      description: CKAN Dataset (Package)
      additionalProperties: true
      properties:
        id:
          type: string
        name:
          type: string
        title:
          type: string
        notes:
          type: string
        url:
          type: string
        version:
          type: string
        author:
          type: string
        author_email:
          type: string
        maintainer:
          type: string
        maintainer_email:
          type: string
        license_id:
          type: string
        owner_org:
          type: string
        private:
          type: boolean
        state:
          type: string
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/Group'
    Tag:
      type: object
      description: CKAN Tag
      additionalProperties: true
      properties:
        id:
          type: string
        name:
          type: string
        display_name:
          type: string
        vocabulary_id:
          type: string
        state:
          type: string
    ErrorEnvelope:
      type: object
      required:
      - help
      - success
      - error
      properties:
        help:
          type: string
        success:
          type: boolean
          default: false
        error:
          type: object
          additionalProperties: true
          properties:
            __type:
              type: string
            message:
              type: string
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: Not found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            not_found_error:
              summary: Not found
              value:
                help: https://demo.ckan.org/api/3/action/help_show?name={action_name}
                success: false
                error:
                  __type: Not Found Error
                  message: Not found
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            validation_error:
              summary: Validation error
              value:
                help: https://demo.ckan.org/api/3/action/help_show?name={action_name}
                success: false
                error:
                  __type: Validation Error
                  name_or_id:
                  - Missing value
    AuthorizationError:
      description: Authorization error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            authorization_error:
              summary: Authorization error
              value:
                help: https://demo.ckan.org/api/3/action/help_show?name={action_name}
                success: false
                error:
                  __type: Authorization Error
                  message: 'Access denied: User not authorized to perform this action'
  securitySchemes:
    ApiTokenAuth:
      type: apiKey
      in: header
      name: Authorization