openapi: 3.0.0
info:
  title: Google Dataset Info API
  description: |
    The Google Dataset Info API returns one dataset from Google Dataset Search, identified by its `dataset_id`,
    with the same metadata as a Google Dataset Search result: title, alternate names, link, description, providers,
    funders, authors, download formats, licenses, last update, covered time period and areas, measured variables and
    techniques, scholarly citation count and citation text.

    **Cross-linking**: Get a `dataset_id` from the `dataset_results` of the Google Dataset Search API and pass it as
    the `dataset_id` parameter. Pass the dataset's `versions.versions_id` as `versions_id` to the Google Dataset Search
    API to list its versions. Each dataset's `cited_by.link` opens the Google Scholar search for articles that cite it.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Google Dataset Info
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["google_dataset_info"]
            default: "google_dataset_info"
        - name: dataset_id
          in: query
          required: true
          description: Identifier of the dataset from the Google Dataset Search API (dataset_results[].dataset_id), also accepted percent-encoded, without its trailing "=" or as a Google Dataset Search link with a docid parameter
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        dataset:
          $ref: '#/components/schemas/Dataset'
        error:
          type: string
          description: Error message when Google Dataset Search returns no dataset for the dataset_id
    Dataset:
      type: object
      required: [dataset_id, title, link, domain]
      properties:
        dataset_id:
          type: string
          description: Google Dataset Search identifier of the dataset
        title:
          type: string
          description: Title of the dataset
        alternate_names:
          type: array
          description: Other names of the dataset
          items:
            type: string
        link:
          type: string
          description: URL of the dataset page at its source
        domain:
          type: string
          description: Host name of the dataset page
        sources:
          type: array
          description: Pages where the dataset can be explored, the one at link first
          items:
            $ref: '#/components/schemas/Source'
        thumbnail:
          type: string
          description: URL of the provider or source logo
        description:
          type: string
          description: Description of the dataset as plain text
        description_links:
          type: array
          description: Links found in the description
          items:
            $ref: '#/components/schemas/DescriptionLink'
        providers:
          type: array
          description: Organizations that provide the dataset
          items:
            $ref: '#/components/schemas/Organization'
        authors:
          type: array
          description: Authors of the dataset
          items:
            $ref: '#/components/schemas/Author'
        funders:
          type: array
          description: Organizations that fund the dataset
          items:
            $ref: '#/components/schemas/Organization'
        formats:
          type: array
          description: Download formats of the dataset
          items:
            $ref: '#/components/schemas/Format'
        has_croissant_format:
          type: boolean
          description: Whether the dataset is available in Croissant, a format for machine learning datasets
        licenses:
          type: array
          description: Licenses of the dataset
          items:
            $ref: '#/components/schemas/License'
        last_updated:
          type: string
          description: Date the dataset was last updated, as Google Dataset Search displays it
        extracted_last_updated:
          type: string
          description: Date the dataset was last updated as YYYY-MM-DD, YYYY-MM or YYYY, at the precision the source gives
        period_covered:
          $ref: '#/components/schemas/PeriodCovered'
        area_covered:
          type: array
          description: Names of the geographic areas the dataset covers
          items:
            type: string
        geographic_coverage:
          $ref: '#/components/schemas/GeographicCoverage'
        variables_measured:
          type: array
          description: Variables the dataset measures
          items:
            type: string
        measurement_techniques:
          type: array
          description: Techniques used to measure the dataset's variables
          items:
            type: string
        cited_by:
          $ref: '#/components/schemas/CitedBy'
        versions:
          $ref: '#/components/schemas/Versions'
        unique_identifier:
          type: string
          description: Persistent identifier URL of the dataset, such as a DOI link
        related_article:
          type: string
          description: URL of an article related to the dataset
        citation:
          type: string
          description: Citation text for the dataset
    DescriptionLink:
      type: object
      required: [link]
      properties:
        title:
          type: string
          description: Text of the link
        link:
          type: string
          description: URL the link points to
    Source:
      type: object
      required: [link]
      properties:
        name:
          type: string
          description: Name of the data catalog that the page says contains the dataset
        link:
          type: string
          description: URL of the dataset page
        domain:
          type: string
          description: Host name of the dataset page
    Organization:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Name of the organization
        link:
          type: string
          description: URL of the organization's website
        thumbnail:
          type: string
          description: URL of the organization's logo
    Author:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Name of the author
    Format:
      type: object
      required: [format]
      properties:
        format:
          type: string
          description: File format or media type, such as csv or application/zip
        size:
          type: integer
          description: File size in bytes
        displayed_size:
          type: string
          description: File size as the source states it, such as 153 KB
    License:
      type: object
      required: [link]
      properties:
        name:
          type: string
          description: Name of the license
        link:
          type: string
          description: URL of the license text
    PeriodCovered:
      type: object
      properties:
        start_date:
          type: string
          description: Start of the covered period as YYYY-MM-DD, YYYY-MM or YYYY
        end_date:
          type: string
          description: End of the covered period as YYYY-MM-DD, YYYY-MM or YYYY
        is_ongoing:
          type: boolean
          description: Whether the covered period continues to the present
    GeographicCoverage:
      type: object
      required: [geometry]
      properties:
        bbox:
          type: array
          description: Bounding box of the covered area as west, south, east and north in degrees
          minItems: 4
          maxItems: 4
          items:
            type: number
        geometry:
          $ref: '#/components/schemas/Geometry'
    Geometry:
      type: object
      description: GeoJSON geometry of the covered area, with longitude before latitude
      required: [type]
      properties:
        type:
          type: string
          enum: [Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection]
          description: GeoJSON geometry type
        coordinates:
          type: array
          description: Positions of the geometry, nested as its type requires
          items: {}
        geometries:
          type: array
          description: Member geometries of a GeometryCollection
          items:
            $ref: '#/components/schemas/Geometry'
    CitedBy:
      type: object
      required: [total]
      properties:
        total:
          type: integer
          description: Number of scholarly articles that cite the dataset
        link:
          type: string
          description: Google Scholar search URL for the articles that cite the dataset
    Versions:
      type: object
      required: [versions_id, link]
      properties:
        versions_id:
          type: string
          description: Version group of the dataset, to pass as versions_id to the Google Dataset Search API
        link:
          type: string
          description: Google Dataset Search page listing the versions of the dataset
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Google Dataset Search URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine identifier
        dataset_id:
          type: string
          description: Identifier of the dataset looked up
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong