findadoctor-si Gp Practices API

openapi: 3.2.0
info:
  title: FindADoctor.si New Zealand Gp Practices API
  version: nz-2026-10-15.2
  description: Read-only JSON API with the same tools as the MCP server. No sign-up needed. Not medical advice; in an emergency call 111. Responses list the main fields (components.schemas); other fields may appear, so ignore fields you do not know. Fields without data are left out.
  x-llms-txt: https://api-nz.findadoctor.si/llms.txt
servers:
- url: https://api-nz.findadoctor.si
security:
- {}
- accountKey: []
tags:
- name: Gp Practices
paths:
  /api/v1/gp-practices:
    get:
      operationId: searchGpPractices
      summary: New Zealand general practices near a place, with enrolment status and fees
      description: 'Free list of New Zealand general practices (GP clinics), or urgent care clinics, near a place, from Healthpoint. Use it when the person needs a GP, wants to enrol with a practice, or needs urgent but not emergency care. Each practice: whether it says it is enrolling new patients (yes; restricted = only some people, e.g. family of patients or people living nearby; no; does not apply = urgent care that does not enrol; unknown = the page does not say), the practice''s own enrolment note, its fee table (the first fee table on its page, usually fees for enrolled patients by age, without and with a Community Services Card; with age, the row for that age), addresses, phone numbers, website, online booking link, languages, hours, the doctors listed there (doctor_ids for get_doctor) and the date Healthpoint says the page was last updated. In New Zealand most people enrol with one general practice: visits cost less once enrolled, and a GP referral is the usual way to a public specialist. Give place or name. Practices are not doctors, so this does not count toward the daily doctor limit. Enrolment and fees change often: tell the person to phone the practice to confirm.'
      parameters:
      - name: place
        in: query
        required: false
        description: New Zealand city, suburb or region (e.g. 'Papanui', 'Hamilton', 'North Shore', 'Canterbury').
        schema:
          type: string
          maxLength: 200
      - name: name
        in: query
        required: false
        description: Practice name or part of it, to check a named practice.
        schema:
          type: string
          maxLength: 200
      - name: enrolling
        in: query
        required: false
        description: yes = only practices that say they are enrolling new patients; yes_or_restricted also keeps practices enrolling only some people (read enrolling_note). Default any (enrolling practices come first).
        schema:
          type: string
          enum:
          - any
          - 'yes'
          - yes_or_restricted
      - name: age
        in: query
        required: false
        description: 'The patient''s age: each result then shows the fee row for that age.'
        schema:
          type: integer
          minimum: 0
          maximum: 120
      - name: language
        in: query
        required: false
        description: Language other than English the practice lists, e.g. 'Mandarin', 'Samoan', 'te reo Maori'.
        schema:
          type: string
          maxLength: 200
      - name: kind
        in: query
        required: false
        description: gp = general practices (default; also nurse-led, online, student and rest-home practices, named so in each result's kind); urgent_care = accident and urgent medical care and after-hours clinics (no enrolment needed); any = both.
        schema:
          type: string
          enum:
          - gp
          - urgent_care
          - any
      - name: limit
        in: query
        required: false
        description: Default 10.
        schema:
          type: integer
          minimum: 1
          maximum: 10
      - name: offset
        in: query
        required: false
        description: For paging (at most 40).
        schema:
          type: integer
          minimum: 0
          maximum: 40
      responses:
        '200':
          description: JSON result (same as the MCP tool's result)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GpResult'
        '400':
          description: 'bad arguments, or the search was too broad (too_slow): the message says what to change'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'the Authorization header was sent but is invalid or expired (invalid_token): send no header or a valid account key'
          headers:
            WWW-Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: rate_limited (too many requests) or daily_limit (daily doctor limit reached); the message says when it resets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: seconds to wait
              schema:
                type: integer
        '500':
          description: internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'busy or starting (busy, unavailable): retry after Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: seconds to wait
              schema:
                type: integer
      tags:
      - Gp Practices
components:
  schemas:
    GpResult:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
        total_matches:
          type: integer
        offset:
          type: integer
        enrolling_counts:
          type: object
          description: matches by enrolling status
        results:
          type: array
          items:
            $ref: '#/components/schemas/GpPractice'
        explain:
          type: string
        next_step:
          type: string
        note:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
          description: bad_args, too_slow, daily_limit, rate_limited, busy, unavailable, sign_in_required, invalid_token, cross_site, not_found, internal
        message:
          type: string
          description: what to change or when to retry
    GpPractice:
      type: object
      properties:
        rank:
          type: integer
        practice:
          type: string
        kind:
          type: string
          enum:
          - general practice
          - urgent care
        enrolling:
          type: string
          enum:
          - 'yes'
          - restricted
          - 'no'
          - does not apply
          - unknown
          description: yes, restricted (only some people), no, does not apply (urgent care), unknown
        enrolling_note:
          type: string
          description: the practice's own words about enrolment
        place_match:
          type: string
          enum:
          - city_or_address
          - city_in_region
          - address_contains
          - region_page_only
        locations:
          type: array
          items:
            type: object
            properties:
              address:
                type: string
              region:
                type: string
              phone:
                type: string
              website:
                type: string
        fees:
          type: array
          items:
            $ref: '#/components/schemas/FeeRow'
        fee_for_age:
          type: object
          description: 'with age: the fee row for that age'
        online_booking:
          type: string
        website:
          type: string
        hours:
          type: array
          items:
            type: string
        languages:
          type: array
          items:
            type: string
        languages_note:
          type: string
        doctors:
          type: array
          items:
            type: object
            properties:
              doctor_id:
                type: string
                pattern: ^nz_[0-9a-z]{12}$
                description: use with get_doctor
              name:
                type: string
        doctors_listed:
          type: integer
        healthpoint:
          type: string
          description: the practice's Healthpoint page
        page_last_updated:
          type: string
    Provider:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
        data_version:
          type: string
      description: who publishes this data and which build
    FeeRow:
      type: object
      properties:
        ages:
          type: string
        without_csc:
          type: string
        with_csc:
          type: string
          description: Community Services Card holders
      description: one row of the practice's fee table (usually fees for enrolled patients)
  securitySchemes:
    accountKey:
      type: http
      scheme: bearer
      description: Optional account key (dk_...); accounts are by invitation during the trial.