openapi: 3.0.0
info:
  title: Google Dataset Search API
  description: |
    The Google Dataset Search API returns the datasets Google Dataset Search finds for a query, with each
    dataset's 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.

    Results can be filtered by update date, download format, usage rights, free access, topic, provider and Croissant
    format, and paged with `page` and `num` through the first 200 results of a query.

    **Cross-linking**: Pass a result's `dataset_id` as the `dataset_id` parameter of the Google Dataset Info API to fetch
    that dataset on its own. Pass a result's `versions.versions_id` as `versions_id` to list the dataset's versions, and
    the `value` of a `filters` option as the parameter its `key` names. Each result's `cited_by.link` opens the Google
    Scholar search for articles that cite the dataset.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Google Dataset Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine identifier
          schema:
            type: string
            enum: ["google_dataset_search"]
            default: "google_dataset_search"
        - name: q
          in: query
          required: false
          description: Search query for datasets, where most emoji count as two characters. Not required if versions_id is present
          schema:
            type: string
            maxLength: 299
        - name: versions_id
          in: query
          required: false
          description: Lists the versions of a dataset, by the versions.versions_id of a result
          schema:
            type: string
            pattern: '^\d{1,20}$'
        - name: time_period
          in: query
          required: false
          description: Restricts results to datasets updated in the past month, year or 3 years
          schema:
            type: string
            enum: ["last_month", "last_year", "last_3_years"]
        - name: file_formats
          in: query
          required: false
          description: 'Comma separated download formats to restrict results to, matching datasets in any of them. Supported values: "tabular", "document", "image", "text", "archive", "structured", "other"'
          schema:
            type: string
        - name: usage_rights
          in: query
          required: false
          description: Restricts results to datasets whose license allows commercial or non-commercial use
          schema:
            type: string
            enum: ["commercial", "noncommercial"]
        - name: is_free
          in: query
          required: false
          description: Set to true to return only datasets described as free to access or under a license that allows redistribution
          schema:
            type: boolean
            default: false
        - name: topics
          in: query
          required: false
          description: 'Comma separated topics to restrict results to, matching datasets on any of them. Supported values: "humanities", "social_sciences", "life_sciences", "agriculture", "natural_sciences", "geo", "computer", "architecture_and_urban_planning", "engineering"'
          schema:
            type: string
        - name: provider_ids
          in: query
          required: false
          description: Comma separated provider ids to restrict results to, matching datasets from any of them. Takes the value of a filters option whose key is provider_ids
          schema:
            type: string
        - name: has_croissant_format
          in: query
          required: false
          description: Set to true to return only datasets available in Croissant, a format for machine learning datasets
          schema:
            type: boolean
            default: false
        - name: page
          in: query
          required: false
          description: Page number of results. (page - 1) * num must stay under 200
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: num
          in: query
          required: false
          description: Number of results per page
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
      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'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        filters:
          type: array
          description: Filters Google Dataset Search offers for the query
          items:
            $ref: '#/components/schemas/Filter'
        dataset_results:
          type: array
          items:
            $ref: '#/components/schemas/Dataset'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message when Google Dataset Search returns no datasets for the query
    SearchInformation:
      type: object
      properties:
        total_results:
          type: integer
          description: Approximate number of datasets Google Dataset Search reports for the query
    Filter:
      type: object
      required: [key, options]
      properties:
        key:
          type: string
          enum: [provider_ids]
          description: Request parameter that takes the value of an option
        options:
          type: array
          items:
            $ref: '#/components/schemas/FilterOption'
    FilterOption:
      type: object
      required: [text, value]
      properties:
        text:
          type: string
          description: Name of the option
        value:
          type: string
          description: Value to pass in the request parameter the filter's key names
    Dataset:
      type: object
      required: [position, dataset_id, title, link, domain]
      properties:
        position:
          type: integer
          description: Position of the dataset in the results, counted across pages
        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
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page number
        next:
          type: integer
          description: Next page number
    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
        q:
          type: string
          description: Search query
        time_period:
          type: string
          description: Update date filter
        file_formats:
          type: string
          description: Comma separated download format filter
        usage_rights:
          type: string
          description: Usage rights filter
        versions_id:
          type: string
          description: Version group of the dataset whose versions are listed
        is_free:
          type: string
          enum: ["true", "false"]
          description: Free access filter
        topics:
          type: string
          description: Comma separated topic filter
        provider_ids:
          type: string
          description: Comma separated provider filter
        has_croissant_format:
          type: string
          enum: ["true", "false"]
          description: Croissant format filter
        page:
          type: integer
          description: Page number
        num:
          type: integer
          description: Number of results per page
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong