openapi: 3.0.3
info:
  title: Dúchas API (National Folklore Collection, UCD) CBÉ CBÉD API
  description: 'The Dúchas API exposes published content from the National Folklore Collection (Cnuasach Bhéaloideas Éireann) held at University College Dublin. It returns JSON across four databases: the Main Manuscript Collection (CBÉ), the Schools'' Collection (CBÉS), the Photographic Collection (CBÉG) and the Persons Database (CBÉD). This description is derived faithfully from the public Dúchas API developer documentation and data dictionary maintained by the Gaois research group.'
  version: 0.5.0
  contact:
    name: Gaois / Dúchas
    email: eolas@duchas.ie
    url: https://docs.gaois.ie
  license:
    name: See Dúchas terms of use
    url: https://www.duchas.ie/en/info/copyright
servers:
- url: https://www.duchas.ie/api/v0.5
  description: Dúchas API v0.5 (prerelease)
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
- BasicAuth: []
tags:
- name: CBÉD
paths:
  /cbed:
    get:
      operationId: getPersons
      summary: Query the Persons Database (CBÉD)
      tags:
      - CBÉD
      parameters:
      - $ref: '#/components/parameters/Gender'
      - $ref: '#/components/parameters/AinmID'
      - $ref: '#/components/parameters/ViafID'
      - $ref: '#/components/parameters/CountyID'
      - $ref: '#/components/parameters/PlaceID'
      - $ref: '#/components/parameters/Country'
      - $ref: '#/components/parameters/GeoNameID'
      - $ref: '#/components/parameters/Occupation'
      - $ref: '#/components/parameters/CreatedBefore'
      - $ref: '#/components/parameters/CreatedSince'
      - $ref: '#/components/parameters/ModifiedBefore'
      - $ref: '#/components/parameters/ModifiedSince'
      responses:
        '200':
          description: A list of person records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /cbed/{id}:
    get:
      operationId: getPersonById
      summary: Get an individual person
      tags:
      - CBÉD
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: A single person record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /cbed/occupations:
    get:
      operationId: getOccupations
      summary: Persons Database occupation reference list
      tags:
      - CBÉD
      responses:
        '200':
          description: Occupation reference list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Occupation'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    Occupation:
      name: Occupation
      in: query
      description: Occupation code, e.g. IASC, FEIRM.
      schema:
        type: string
    ViafID:
      name: ViafID
      in: query
      schema:
        type: integer
    Country:
      name: Country
      in: query
      description: ISO 3166-1 alpha-2 code; UK subdivisions use GB-ENG, GB-NIR, GB-SCT, GB-WLS.
      schema:
        type: string
    ModifiedBefore:
      name: ModifiedBefore
      in: query
      schema:
        type: string
        format: date-time
    GeoNameID:
      name: GeoNameID
      in: query
      schema:
        type: integer
    CreatedSince:
      name: CreatedSince
      in: query
      schema:
        type: string
        format: date-time
    CountyID:
      name: CountyID
      in: query
      schema:
        type: integer
    CreatedBefore:
      name: CreatedBefore
      in: query
      schema:
        type: string
        format: date-time
    Gender:
      name: Gender
      in: query
      schema:
        type: string
        enum:
        - f
        - m
    PlaceID:
      name: PlaceID
      in: query
      schema:
        type: integer
    AinmID:
      name: AinmID
      in: query
      schema:
        type: integer
    ModifiedSince:
      name: ModifiedSince
      in: query
      schema:
        type: string
        format: date-time
  schemas:
    Country:
      type: object
      properties:
        IsoCode:
          type: string
          description: ISO 3166-1/2 code.
        GeoNameID:
          type: integer
        NameEN:
          type: string
        NameGA:
          type: string
        Coordinates:
          $ref: '#/components/schemas/Coordinates'
    Coordinates:
      type: object
      properties:
        Latitude:
          type: number
          format: double
        Longitude:
          type: number
          format: double
    LocationIreland:
      type: object
      properties:
        LogainmID:
          type: integer
        NameEN:
          type: string
        NameGA:
          type: string
        Coordinates:
          $ref: '#/components/schemas/Coordinates'
        Counties:
          type: array
          items:
            $ref: '#/components/schemas/County'
    Age:
      type: object
      properties:
        Age:
          type: integer
        Qualifier:
          type: string
          enum:
          - APPROX
          - OVER
        RangeMax:
          type: integer
    Name:
      type: object
      properties:
        FirstNames:
          type: string
        Surname:
          type: string
        FullName:
          type: string
    County:
      type: object
      properties:
        LogainmID:
          type: integer
        NameEN:
          type: string
        NameGA:
          type: string
        QualifiedNameEN:
          type: string
        QualifiedNameGA:
          type: string
        Coordinates:
          $ref: '#/components/schemas/Coordinates'
    LocationAbroad:
      type: object
      properties:
        GeoNameID:
          type: integer
        NameEN:
          type: string
        NameGA:
          type: string
        Coordinates:
          $ref: '#/components/schemas/Coordinates'
        Country:
          $ref: '#/components/schemas/Country'
    Occupation:
      type: object
      properties:
        ID:
          type: string
        NameEN:
          type: string
        NameGA:
          type: string
    Date:
      type: object
      properties:
        IsoDate:
          type: string
          format: date
        IsoStartDate:
          type: string
          format: date
        IsoEndDate:
          type: string
          format: date
        IsoDuration:
          type: string
        Accuracy:
          type: string
          enum:
          - APPROX
          - INFER
          - QUESTION
        Year:
          type: integer
        Month:
          type: integer
        Day:
          type: integer
        PeriodStartYear:
          type: integer
        PeriodStartMonth:
          type: integer
        PeriodStartDay:
          type: integer
        PeriodEndYear:
          type: integer
        PeriodEndMonth:
          type: integer
        PeriodEndDay:
          type: integer
    Person:
      type: object
      properties:
        ID:
          type: integer
        DateCreated:
          type: string
          format: date-time
        DateModified:
          type: string
          format: date-time
        Names:
          type: array
          items:
            $ref: '#/components/schemas/Name'
        Gender:
          type: string
          enum:
          - f
          - m
        Age:
          $ref: '#/components/schemas/Age'
        AinmID:
          type: integer
        ViafID:
          type: integer
        BirthDate:
          $ref: '#/components/schemas/Date'
        DeathDate:
          $ref: '#/components/schemas/Date'
        BirthCounty:
          $ref: '#/components/schemas/County'
        BirthPlaceIreland:
          $ref: '#/components/schemas/LocationIreland'
        BirthCountry:
          $ref: '#/components/schemas/Country'
        BirthPlaceAbroad:
          $ref: '#/components/schemas/LocationAbroad'
        Counties:
          type: array
          items:
            $ref: '#/components/schemas/County'
        AddressesIreland:
          type: array
          items:
            $ref: '#/components/schemas/LocationIreland'
        Countries:
          type: array
          items:
            $ref: '#/components/schemas/Country'
        AddressesAbroad:
          type: array
          items:
            $ref: '#/components/schemas/LocationAbroad'
        Occupations:
          type: array
          items:
            $ref: '#/components/schemas/Occupation'
        CollectorRelationship:
          type: string
          enum:
          - GRPAR
          - PAR
          - REL
          - UNK
          - UNREL
  responses:
    NotFound:
      description: Not Found — resource does not exist.
    Unauthorized:
      description: Unauthorized — missing or invalid API key.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
    BasicAuth:
      type: http
      scheme: basic
      description: Username is the API key; password is empty.