DataScoop Datasets API

openapi: 3.2.0
info:
  title: DataScoop Datasets API
  version: 1.0.0
  summary: 'Official public datasets as filtered rows: CSV, JSON and MCP.'
  description: 'Preview any dataset free (25 rows per call, no key). Pro keys can access every matching row: REST JSON returns up to 10,000 rows per page, with offset for pagination; omit limit for a full Pro CSV export. Fields marked personal in the schema are excluded; every response carries the attribution to keep. MCP endpoint: https://datascoop.io/mcp. Machine-readable overview: https://datascoop.io/llms.txt'
  termsOfService: https://datascoop.io/terms
  contact:
    url: https://datascoop.io/contact
  license:
    name: Data reused under the open licence listed per dataset
    url: https://datascoop.io/licences
servers:
- url: https://datascoop.io
security:
- {}
- bearerAuth: []
- apiKeyQuery: []
tags:
- name: Datasets
paths:
  /v1/datasets:
    get:
      operationId: listDatasets
      summary: List datasets
      description: Every dataset with its country, coverage, row count, licence and refresh date.
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
          enum:
          - GB
          - US
          - AU
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  datasets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Dataset'
                  countries:
                    type: array
                    items:
                      type: object
      tags:
      - Datasets
  /v1/datasets/{id}:
    get:
      operationId: getDatasetSchema
      summary: Columns and filters of a dataset
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          enum:
          - cqc
          - fsa
          - us-food-inspections
          - us-building-permits
          - fhis-scotland
          - charity-commission
          - companies-house
          - us-motor-carriers
          - us-business-licenses
          - us-liquor-licenses
          - au-aged-care
      responses:
        '200':
          description: OK
        '404':
          description: Unknown dataset
      tags:
      - Datasets
  /v1/datasets/{id}/query:
    get:
      operationId: queryDataset
      summary: Query any dataset (generic form)
      description: Filters are query parameters named after the dataset's filter keys (see GET /v1/datasets/{id}). The per-dataset operations below list them explicitly.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          enum:
          - cqc
          - fsa
          - us-food-inspections
          - us-building-permits
          - fhis-scotland
          - charity-commission
          - companies-house
          - us-motor-carriers
          - us-business-licenses
          - us-liquor-licenses
          - au-aged-care
      - name: limit
        in: query
        required: false
        description: Rows to return. Free plans are capped at 25; Pro up to 10,000 per JSON or explicitly limited CSV page. Omit limit for a full Pro CSV export.
        schema:
          type: integer
          minimum: 0
      - name: offset
        in: query
        required: false
        description: Rows to skip. Supported by anonymous, free-key and Pro queries. Ignored for a full Pro CSV export when limit is omitted.
        schema:
          type: integer
          minimum: 0
      - name: format
        in: query
        required: false
        description: json (default) or csv. With Pro, format=csv without limit streams every matching row. With an explicit limit, CSV returns a bounded page and respects offset.
        schema:
          type: string
          enum:
          - json
          - csv
      - name: strict_filters
        in: query
        required: false
        description: Set to 1 or true to reject unsupported or invalid nonempty filters with HTTP 400. Omitted filters and empty values remain absent. Default is lenient; check ignored before using results. This is a request option, not a dataset filter.
        schema:
          type: string
          enum:
          - '0'
          - '1'
          - 'false'
          - 'true'
          default: '0'
      responses:
        '200':
          description: Matching rows; CSV preserves its existing columns and attribution comments, without the JSON metadata envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
            text/csv:
              schema:
                type: string
        '400':
          description: Invalid filters, strict-mode option or pagination
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/InvalidFilters'
                - type: object
                  properties:
                    error:
                      type: string
                    code:
                      type: string
                      enum:
                      - invalid_strict_filters
                      - invalid_pagination
                  required:
                  - error
        '404':
          description: Unknown dataset
      tags:
      - Datasets
  /v1/datasets/cqc/intelligence:
    get:
      operationId: get_cqc_intelligence
      summary: Care-home territory intelligence
      description: Complete aggregate totals, registered providers, recorded beds, field coverage and the largest 25 matching registered providers. England care homes only. Uses the same strict filters as the location query; careHome defaults to true. Source-import dates are not publication or inspection dates. Cold reports return 202 without totals; retry after Retry-After.
      parameters:
      - name: locationId
        in: query
        required: false
        description: 'CQC location ID (exact): exact match, case-sensitive. Exact published CQC location identifier. Keep identifiers as strings.'
        schema:
          type: string
        example: 1-100000000
      - name: providerId
        in: query
        required: false
        description: 'CQC provider ID (exact): exact match, case-sensitive. Exact registered-provider identifier, not a verified ultimate owner or brand group.'
        schema:
          type: string
        example: 1-100000001
      - name: region
        in: query
        required: false
        description: 'Region: exact match, case-insensitive.'
        schema:
          type: string
          enum:
          - East Midlands
          - East of England
          - London
          - North East
          - North West
          - South East
          - South West
          - West Midlands
          - Yorkshire and The Humber
        example: London
      - name: localAuthority
        in: query
        required: false
        description: 'Local authority contains: substring match, case-insensitive.'
        schema:
          type: string
        example: Leeds
      - name: localAuthorityExact
        in: query
        required: false
        description: 'Local authority (exact name): exact match, case-sensitive. Use the full local-authority name exactly as published, including its case. York matches York only, not Yorkshire authorities.'
        schema:
          type: string
        example: York
      - name: careHome
        in: query
        required: false
        description: 'Care homes only: true to apply. Residential and nursing homes only'
        schema:
          type: boolean
        example: true
      - name: serviceType
        in: query
        required: false
        description: 'Service type contains: substring match, case-insensitive. e.g. Residential homes, Nursing homes, Homecare agencies, Supported living, Dentist, Doctors/GPs, Hospital, Hospice, Clinic, Ambulances, Diagnosis/screening'
        schema:
          type: string
        example: Nursing homes
      - name: specialism
        in: query
        required: false
        description: 'Specialism contains: substring match, case-insensitive.'
        schema:
          type: string
        example: Dementia
      - name: postcodeArea
        in: query
        required: false
        description: 'Postcode area: prefix match, case-insensitive.'
        schema:
          type: string
        example: LS
      - name: nameContains
        in: query
        required: false
        description: 'Name contains: substring match, case-insensitive.'
        schema:
          type: string
        example: Manor
      - name: providerContains
        in: query
        required: false
        description: 'Provider contains: substring match, case-insensitive.'
        schema:
          type: string
        example: Barchester
      - name: overallRating
        in: query
        required: false
        description: 'Overall rating: exact match, case-insensitive. Match a published rating in the imported data. Missing ratings do not match. Hosted DataScoop queries need no customer CQC key; field availability depends on the imported source.'
        schema:
          type: string
          enum:
          - Outstanding
          - Good
          - Requires improvement
          - Inadequate
        example: Inadequate
      - name: minBeds
        in: query
        required: false
        description: 'Minimum beds: minimum (inclusive). At least this many registered beds, not available beds. Missing capacity does not match a positive threshold. Hosted DataScoop queries need no customer CQC key; field availability depends on the imported source.'
        schema:
          type: number
        example: 40
      responses:
        '200':
          description: Ready dated report with importVersion, applied_filters, summary, providers, explicit provider truncation, history availability, provenance, licence and attribution
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - dataset
                - importVersion
                - summary
                - providers
                - applied_filters
                - provenance
                - licence
                - attribution
                properties:
                  status:
                    const: ready
                  dataset:
                    const: cqc
                  importVersion:
                    type: string
                  summary:
                    type: object
                    description: locations, registeredProviders, locationsWithoutProviderId, recordedBeds, bedCoverage (positive/zero/missing/invalid), fieldAvailability
                  providers:
                    type: array
                    maxItems: 25
                    items:
                      type: object
                  providersReturned:
                    type: integer
                  providersTotal:
                    type: integer
                  providersTruncated:
                    type: boolean
        '202':
          description: Preparing report; Retry-After gives seconds to wait. No partial totals.
        '400':
          description: Invalid filters, strict-mode option or pagination
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/InvalidFilters'
                - type: object
                  properties:
                    error:
                      type: string
                    code:
                      type: string
                      enum:
                      - invalid_strict_filters
                      - invalid_pagination
                  required:
                  - error
        '503':
          description: Source, worker or report queue unavailable; retry later.
      tags:
      - Datasets
components:
  schemas:
    QueryResult:
      type: object
      properties:
        dataset:
          type: string
        plan:
          type: string
          enum:
          - free
          - pro
        importVersion:
          type:
          - string
          - 'null'
          description: Opaque source-import identity, stable across deployments.
        total:
          type: integer
          description: Rows matching the filters
        returned:
          type: integer
        offset:
          type: integer
        truncated:
          type: boolean
          description: true when fewer rows than total were returned
        ignored:
          type: array
          items:
            type: string
          description: Filter keys the dataset does not know
        columns:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              label:
                type: string
        rows:
          type: array
          items:
            type: object
            additionalProperties: true
        attribution:
          type: string
          description: Keep this with the data
        licence:
          type: string
        applied_filters:
          type: object
          additionalProperties:
            type:
            - string
            - number
            - boolean
          description: Effective dataset predicates after normalisation. Does not include pagination or request options.
        provenance:
          type: object
          properties:
            source_urls:
              type: array
              items:
                type: string
                format: uri
              description: Configured publisher references; not retained versions of imported files
            licence_url:
              type:
              - string
              - 'null'
              format: uri
            imported_at:
              type:
              - string
              - 'null'
              format: date-time
              description: Recorded successful DataScoop import time, not a publisher release date or record update time
            coverage:
              type: object
              properties:
                country:
                  type: string
                region:
                  type:
                  - string
                  - 'null'
              required:
              - country
              - region
              description: Declared dataset geography; not a guarantee of completeness
            notes:
              type: array
              items:
                type: string
          required:
          - source_urls
          - licence_url
          - imported_at
          - coverage
          - notes
        next_step:
          type: object
          description: May offer a CSV or larger paid pages when total exceeds the free per-call cap. Free offset pagination remains available.
          properties:
            message:
              type: string
            buy_export_url:
              type: string
              format: uri
            signup_url:
              type: string
              format: uri
            pricing_url:
              type: string
              format: uri
      required:
      - dataset
      - total
      - returned
      - truncated
      - rows
      - attribution
      - applied_filters
      - provenance
    Dataset:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        country:
          type: string
        region:
          type:
          - string
          - 'null'
        licence:
          type: string
        attribution:
          type: string
        row_count:
          type: integer
        refreshed_at:
          type: string
          format: date-time
    InvalidFilters:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          const: invalid_filters
        filter_names:
          type: array
          maxItems: 32
          items:
            type: string
          description: Bounded names only; invalid values are not echoed
      required:
      - error
      - code
      - filter_names
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: DataScoop API key from /signup
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
externalDocs:
  url: https://datascoop.io/docs
  description: Docs