openapi: 3.2.0
info:
  title: University of Florida Libraries Patron Search API
  version: '2026-09-01'
  summary: Public, unauthenticated read API over the University of Florida Digital Collections, the Digital Library of the Caribbean and the Florida Digital Newspaper Library.
  description: '`api.patron.uflib.ufl.edu` is the backend of the UF Digital Collections reader at

    ufdc.ufl.edu.'
  contact:
    name: UF Digital Library Center
    email: digby@ufl.edu
    url: https://lts.uflib.ufl.edu/supported-systems/uf-digital-collections/
  x-operator: institution
  x-operator-basis: api.patron.uflib.ufl.edu -> 128.227.18.113, 128.227.24.223; ARIN NetName UFNET, OrgName "University of Florida", CIDR 128.227.0.0/16. No vendor CNAME. TLS issuer "C=US, O=Internet2, CN=InCommon RSA Server CA 2". The OAI-PMH Identify response names UF as the repository and digby@ufl.edu as adminEmail. No vendor product string appears in any probed response.
  x-provenance:
    generated: '2026-09-01'
    method: derived
    source: Live HTTP probes of every resource named in the root index of https://api.patron.uflib.ufl.edu on 2026-09-01, plus the self-documenting example URLs each resource root returns. The host itself was discovered by reading https://ufdc.ufl.edu/assets/environment-CtcEkdJa.js, the UFDC client's build-time environment module.
servers:
- url: https://api.patron.uflib.ufl.edu
  description: 'Production. Public and unauthenticated; no API key is issued or required.


    WARNING — the hostname resolves to TWO A records that do not serve the same routes.

    128.227.18.113 serves every resource. 128.227.24.223 serves every resource EXCEPT

    /oai and /oai_by_title, which it returns 404 for. Verified 2026-09-01 by pinning

    each address with --resolve and replaying all nine sampled routes against both. See

    `x-node-divergence`.'
tags:
- name: Search
  description: Full-text, exact, geospatial and page-level search.
paths:
  /exactsearch:
    get:
      tags:
      - Search
      operationId: exactSearch
      summary: Search items across the digital collections
      description: Called with no parameters, returns worked example URLs for itself. Called with parameters, returns a hit list with facet buckets. Quote the `default` value to force phrase matching.
      parameters:
      - name: default
        in: query
        description: Free-text query; wrap in double quotes for an exact phrase.
        schema:
          type: string
          examples:
          - '"elmer h. bone"'
      - name: subject_keyword
        in: query
        description: Restrict to a subject keyword.
        schema:
          type: string
      - name: datelo
        in: query
        description: Earliest publication date, YYYY-MM-DD.
        schema:
          type: string
          format: date
      - name: datehi
        in: query
        description: Latest publication date, YYYY-MM-DD.
        schema:
          type: string
          format: date
      - name: filter
        in: query
        description: Facet filter in `field:value` form, e.g. `genre:novel`.
        schema:
          type: string
      responses:
        '200':
          description: Hits plus facet buckets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
  /pagetext:
    get:
      tags:
      - Search
      operationId: searchPageText
      summary: Full-text search inside digitised page images
      description: Searches the OCR text of scanned pages. Scope narrows from the whole corpus to a single serial (`bibid`) to a single volume (`bibid` + `vid`).
      parameters:
      - name: term
        in: query
        description: Single term to match.
        schema:
          type: string
      - name: fuzzy
        in: query
        description: Fuzzy-match the term.
        schema:
          type: boolean
      - name: phrase
        in: query
        description: Multi-word phrase to match.
        schema:
          type: string
      - name: bibid
        in: query
        description: Restrict to one bibliographic record.
        schema:
          type: string
          examples:
          - UF00028290
      - name: vid
        in: query
        description: Restrict to one volume within the bibid.
        schema:
          type: string
          examples:
          - '00001'
      responses:
        '200':
          description: Matching pages.
          content:
            application/json:
              schema:
                type: object
  /mapsearch:
    get:
      tags:
      - Search
      operationId: mapSearch
      summary: Geospatial search over georeferenced items
      parameters:
      - name: mapsearchtype
        in: query
        required: true
        description: Bounding-box or radius search.
        schema:
          type: string
          enum:
          - box
          - point
      - name: minlat
        in: query
        schema:
          type: number
      - name: maxlat
        in: query
        schema:
          type: number
      - name: minlng
        in: query
        schema:
          type: number
      - name: maxlng
        in: query
        schema:
          type: number
      - name: pointlat
        in: query
        schema:
          type: number
      - name: pointlng
        in: query
        schema:
          type: number
      - name: maxdist
        in: query
        description: Radius with unit suffix, e.g. `1km`, `10km`.
        schema:
          type: string
      - name: aggregationcodes
        in: query
        description: Restrict to a collection aggregation code.
        schema:
          type: string
      - name: mediatype
        in: query
        description: Restrict to a media type, e.g. `Photograph`.
        schema:
          type: string
      responses:
        '200':
          description: Georeferenced hits.
          content:
            application/json:
              schema:
                type: object
  /serialtitles:
    get:
      tags:
      - Search
      operationId: searchSerialTitles
      summary: Search serial titles
      parameters:
      - name: title
        in: query
        schema:
          type: string
          examples:
          - leader
      responses:
        '200':
          description: Matching serial titles.
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    Hit:
      type: object
      properties:
        did:
          type: string
          description: '`BIBID:VID`.'
        bibid:
          type: string
        vid:
          type: string
        title:
          type: string
        mediatype:
          type: string
        aggregationcodes:
          type: array
          items:
            type: string
        mainthumbnail:
          type: string
        mainjpeg:
          type: string
        pagecount:
          type: integer
        language:
          type: array
          items:
            type: string
        creator:
          type: array
          items:
            type: string
        subject_keyword:
          type: array
          items:
            type: string
        genre:
          type: array
          items:
            type: string
        source_institution:
          type: string
        holding_location:
          type: string
        publication_date:
          type: string
        conv_date:
          type: string
          description: Normalised date, YYYY-MM-DD.
        collections:
          type: array
          items:
            type: string
        general_note:
          type: array
          items:
            type: string
        ip_restriction_mask:
          type:
          - integer
          - string
        made_public_date:
          type: string
        hit_reason:
          type:
          - string
          - array
          - object
    SearchResult:
      type: object
      required:
      - hits
      properties:
        query:
          type:
          - string
          - object
        hit_count:
          type: integer
        filter_buckets:
          type: object
          description: Facet counts keyed by field.
        hits:
          type: array
          items:
            $ref: '#/components/schemas/Hit'
        ip:
          type: string
          description: The API echoes the CALLER's own IP address back in this field. It is not institutional data and must not be stored in a catalogued example.
x-node-divergence:
  observed: '2026-09-01'
  method: probed
  hosts:
  - address: 128.227.18.113
    routes_ok: all sampled
  - address: 128.227.24.223
    routes_404:
    - /oai
    - /oai_by_title
    routes_ok:
    - /
    - /types
    - /exactsearch
    - /recent_additions
    - /rss_ufdc
    - /collections
    - /fdnl_titles_list
  impact: An OAI-PMH harvester that resolves onto the second node receives HTTP 404 and concludes the repository has been withdrawn. Which node answers is a DNS ordering accident, so the failure is intermittent and will not reproduce on a retry that lands on the other address. This is deployment drift between two backends, not a deliberate partition — every other route is served identically by both.