findadoctor-si Procedure Volumes API

openapi: 3.2.0
info:
  title: FindADoctor.si France Procedure Volumes API
  version: fr-2026-10-16.1
  description: 'Read-only JSON API with the same tools as the MCP server. No sign-up needed. Not medical advice; in an emergency call 15 (SAMU) or 112. Responses list the main fields (components.schemas); other fields may appear, so ignore fields you do not know. Fields without data are left out. Doctor details include Transparence Santé data (licence CC BY-NC-SA 4.0): keep the source and licence when you reuse them. Responses are not for search-engine indexing (X-Robots-Tag: noindex).'
  x-llms-txt: https://api-fr.findadoctor.si/llms.txt
servers:
- url: https://api-fr.findadoctor.si
security:
- {}
- accountKey: []
tags:
- name: Procedure Volumes
paths:
  /api/v1/procedure-volumes:
    get:
      operationId: hospitalProcedureVolumes
      summary: Which French hospitals and clinics perform a procedure most (Open CCAM)
      description: 'Which French hospitals and private clinics perform a procedure most, from Open CCAM (ATIH): number of acts per hospital site per year, 2021-2025, public and private. Counts hospital stays and day cases only (PMSI MCO); procedures done in a doctor''s office or a hospital outpatient clinic are not counted, and a site with fewer than 11 stays for an act is not listed. procedure = English or French text (''cataract'', ''knee replacement'', ''prothèse genou'', ''coloscopie'', ''ablation fibrillation auriculaire'') or CCAM codes; the reply lists the CCAM acts it added up, so check they fit the need (add-on codes and pathology are left out of text matches). For ''aneurysm'' or ''stent'' say where (brain, aorta, heart, carotid). place = city, postcode, Paris/Lyon/Marseille arrondissement, département number or a hospital FINESS number; without place it ranks all of France. Hospital-level only: it does not say which surgeon operates. Then use search_doctors with hospital_finess (salaried hospital doctors) or with the hospital''s postcode and the specialty (self-employed surgeons at private clinics). Free. On this web API pass the procedure as text or CCAM codes in procedure (the codes list is MCP only).'
      parameters:
      - name: procedure
        in: query
        required: false
        description: Procedure in English or French, or CCAM codes (e.g. 'BFGA427'; an 8th phase digit is dropped).
        schema:
          type: string
          maxLength: 200
      - name: place
        in: query
        required: false
        description: City, postcode, arrondissement ('Paris 15'), département number (2A, 2B, 971-976), or hospital FINESS number.
        schema:
          type: string
          maxLength: 200
      - name: year
        in: query
        required: false
        description: Default latest (2025).
        schema:
          type: integer
          minimum: 2021
          maximum: 2025
      - name: limit
        in: query
        required: false
        description: Default 10.
        schema:
          type: integer
          minimum: 1
          maximum: 20
      - name: offset
        in: query
        required: false
        description: For paging (at most 100).
        schema:
          type: integer
          minimum: 0
          maximum: 100
      responses:
        '200':
          description: JSON result (same as the MCP tool's result)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HospitalVolumes'
        '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:
      - Procedure Volumes
components:
  schemas:
    HospitalVolumes:
      type: object
      properties:
        before_you_answer:
          type: string
          description: 'read first: translate the French act labels; counts are per site, not per surgeon'
        provider:
          $ref: '#/components/schemas/Provider'
        year:
          type: integer
        count:
          type: integer
        more:
          type: boolean
        offset:
          type: integer
        acts_counted:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              label:
                type: string
              france_acts_this_year:
                type: integer
          description: 'the CCAM acts added up: check they fit the need'
        acts_note:
          type: string
        france_total:
          type: object
          properties:
            acts:
              type: integer
            hospital_sites:
              type: integer
            note:
              type: string
        area_hospital_sites:
          type: integer
        hospitals:
          type: array
          items:
            $ref: '#/components/schemas/HospitalVolume'
        place_note:
          type: string
        next_step:
          type: string
        note:
          type: string
    Provider:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
        data_version:
          type: string
      description: who publishes this data and which build
    HospitalVolume:
      type: object
      properties:
        finess:
          type: string
          description: hospital site FINESS number (use with search_doctors hospital_finess)
        name:
          type: string
        postcode:
          type: string
        city:
          type: string
        departement:
          type: string
        acts:
          type: integer
          description: acts counted for the year asked
        stays:
          type: integer
        same_day_share:
          type: number
        avg_nights:
          type: number
        acts_by_code:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              acts:
                type: integer
        acts_by_year:
          type: object
          description: acts per year, 2021-2025
        doctors_with_register_address_here:
          type: integer
    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
  securitySchemes:
    accountKey:
      type: http
      scheme: bearer
      description: Optional account key (dk_...); accounts are by invitation during the trial.