Raw schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"US",
"NZ",
"FR"
],
"description": "Where the person wants to be seen: United States (country=US), New Zealand (country=NZ), France (country=FR). Decide it before searching; if unclear, ask the person. Older clients that leave it out get United States."
},
"condition": {
"type": "string",
"maxLength": 200,
"description": "(US only) Disease, symptom or problem, e.g. 'atrial fibrillation', 'knee osteoarthritis', 'breast cancer', 'migraine'."
},
"procedure": {
"type": "string",
"maxLength": 200,
"description": "(US only) Procedure or surgery, e.g. 'knee replacement', 'TAVR', 'cataract surgery', 'Mohs surgery'. See list_procedures."
},
"specialty": {
"type": "string",
"maxLength": 200,
"description": "US: Specialty id, name, title or family, e.g. 'cardiology', 'cardiologist', 'ENT', 'GI', 'OB/GYN', 'primary care', 'pediatric neurology', 'palliative care', 'orthopaedic-surgery'. See list_specialties. NZ: Specialty name, a word from one, or a plain word like 'eye' (see list_specialties). FR: Specialty in French or English, e.g. 'cardiologie', 'dermatology', 'ORL', 'GP' (see list_specialties)."
},
"state": {
"type": "string",
"maxLength": 200,
"description": "(US only) US state, 2-letter code (MA) or full name. With within_miles it only identifies the city (the radius can cross state lines) and is ignored with near_zip."
},
"city": {
"type": "string",
"maxLength": 200,
"description": "(US only) City of a practice location. Alone it matches only that exact city name (suburbs are separate cities); for a metro area add within_miles, e.g. city='Dallas', state='TX', within_miles=25."
},
"near_zip": {
"type": "string",
"maxLength": 200,
"description": "(US only) One or more US ZIP codes, comma-separated. With within_miles: practices within that distance of these ZIPs. Without it: practices in the same 3-digit ZIP areas (one area can be only part of a big metro, e.g. Brooklyn 112 but not Manhattan 100-102)."
},
"within_miles": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "(US only) Search radius in miles around city (give state too) or near_zip, e.g. 25 for a metro area, 5-10 in a dense city such as New York City, Chicago, San Francisco or Boston (25 there spans the whole metro); includes suburbs and can cross state lines. Each result then has distance_miles."
},
"patient": {
"type": "string",
"enum": [
"adult",
"child"
],
"description": "(US only) adult removes child-only specialties; child lists pediatric specialists and doctors listed on a children's hospital's own website (listed_on_childrens_hospital_website in results) first, unless there is evidence that they mainly treat adults."
},
"accepting_new_patients": {
"type": "boolean",
"description": "(US only) true keeps only doctors listed as accepting new patients by their hospital website (others are unknown, not 'no'; confirm when booking)."
},
"language": {
"type": "string",
"maxLength": 200,
"description": "US: Language the doctor speaks other than English, e.g. 'Spanish', 'Mandarin', 'Vietnamese' (several: 'Spanish, Portuguese' = any of them). Keeps only doctors whose hospital website lists it (one site lists office staff's languages too); most doctors have no such page here, so if few results, also search the web. NZ: Language other than English the doctor, or a small clinic (3 doctors or fewer) they work in, lists, e.g. 'Mandarin', 'Hindi', 'Samoan'. FR: Language other than French, e.g. 'English', 'Arabic', 'anglais'. Only known for doctors with a Maiia or hospital profile (about 1,800 list one); many others speak it too."
},
"gender": {
"type": "string",
"enum": [
"female",
"male"
],
"description": "female or male. US: Doctor's gender (NPI registry). NZ: Only when the person asks. Gender is recorded for only a small share of doctors (when their Healthpoint page states it); doctors without it are left out and gender_note says how many. FR: Only when the person asks. From the register's civil title (Madame/Monsieur); recorded for almost all doctors."
},
"medicare_patient": {
"type": "boolean",
"description": "(US only) true for a person 65 or older or on Medicare: leaves out doctors on the CMS Medicare opt-out list (Medicare and Medicare Advantage plans will not pay them except for emergency or urgent care). Without it such doctors carry a WARNING in warnings."
},
"text": {
"type": "string",
"maxLength": 200,
"description": "(US only) Free-text filter over specialty, medical school, hospitals, medical group and procedure groups, e.g. a hospital name. Insurance is not searchable (some hospital-website lists are shown in results, not filtered); for languages use language."
},
"name": {
"type": "string",
"maxLength": 200,
"description": "US: Part of the doctor's name. Name searches also return NPI records that are probably not physicians (nurse practitioners, physician assistants, etc.), marked with a WARNING; other searches leave them out. NZ: Doctor's name or part of it, to check a named doctor. FR: Doctor's name or part of it, to check a named doctor."
},
"sort": {
"type": "string",
"enum": [
"evidence",
"volume",
"standing"
],
"description": "(US only) evidence (default), volume (best Medicare procedure rank first) or standing (named principal investigator on industry-sponsored research first)."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "Default 10."
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 20,
"description": "US: For paging (at most 20, so 30 results in all: narrow the search instead of paging further). NZ: For paging (at most 20, so 30 results in all: narrow the search instead). FR: For paging (at most 20, so 30 results in all: narrow the search instead)."
},
"need": {
"type": "string",
"maxLength": 200,
"description": "NZ: Condition, procedure or focus, plain English. FR: Condition, procedure or focus, in French or English."
},
"place": {
"type": "string",
"maxLength": 200,
"description": "NZ: New Zealand city, suburb, or region or Health NZ district (e.g. 'Waikato', 'Hawke's Bay', 'Capital and Coast'). FR: City, postcode, arrondissement ('Paris 15'), département number ('69', '2A') or a practice or hospital name."
},
"sector": {
"type": "string",
"enum": [
"any",
"private",
"public"
],
"description": "(NZ only) private = the doctor lists a private service; public = a public (Health NZ) service. Default any."
},
"child": {
"type": "boolean",
"description": "(NZ only) True when the patient is a child: among doctors in the same place who match the need equally well, those in paediatrics or who list children in their focus come first, then those whose services say they see children; doctors whose services list only adult ages are left out. Most listings do not say, so those doctors stay in."
},
"southern_cross_affiliated": {
"type": "boolean",
"description": "(NZ only) True keeps doctors whose own Healthpoint page or at least one of whose service pages says Southern Cross Affiliated Provider (cover still depends on the policy and often prior approval; confirm)."
},
"experienced_first": {
"type": "boolean",
"description": "(NZ only) True when the person wants an experienced or senior doctor: among doctors who match equally well, those longer on the New Zealand specialist (vocational) register come first. Time on the register is not quality, and doctors who trained overseas may have practised longer than it shows."
},
"fee_sector": {
"type": "string",
"enum": [
"any",
"secteur_1",
"secteur_1_or_optam",
"secteur_2"
],
"description": "(FR only) Assurance Maladie fee category. secteur_1 = standard fees, no extra charges; secteur_1_or_optam = standard fees or agreed limits on extra fees; secteur_2 = may charge extra. Kept if ANY of the doctor's practices has it (it can differ by practice): check each practice in get_doctor. Most hospital-only doctors have no category. Default any."
},
"online_booking": {
"type": "boolean",
"description": "(FR only) True keeps doctors whose Maiia or hospital page shows online booking (Doctolib is not covered)."
},
"teleconsultation": {
"type": "boolean",
"description": "(FR only) True keeps doctors offering video consultations on Maiia."
},
"hospital_finess": {
"type": "string",
"maxLength": 200,
"description": "(FR only) Keep doctors whose register address is this hospital site (FINESS number from hospital_procedure_volumes): mostly salaried hospital doctors."
}
},
"required": [
"country"
],
"additionalProperties": false
}