SearchResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/findadoctor-si/json-schema/findadoctor-si-search-result-schema.json",
  "title": "SearchResult",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/findadoctor-si-openapi.json#/components/schemas/SearchResult",
  "type": "object",
  "properties": {
    "provider": {
      "$ref": "#/$defs/Provider"
    },
    "before_answering": {
      "type": "string",
      "description": "read this before answering the person"
    },
    "interpreted": {
      "type": "object",
      "properties": {
        "condition_mesh": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "mesh_ui": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "match": {
                "type": "string"
              }
            }
          },
          "description": "standard medical terms (MeSH) the condition was read as"
        },
        "volume_from_procedure_groups": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "location": {
          "type": "object",
          "properties": {
            "state": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "near_zip3_areas": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "near_zip without within_miles: whole 3-digit ZIP areas"
            },
            "center": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "within_miles: the place the distance is measured from"
            },
            "within_miles": {
              "type": "number"
            },
            "zip_codes_in_area": {
              "type": "integer"
            },
            "note": {
              "type": "string"
            }
          },
          "description": "state/city/near_zip3_areas without within_miles; center/within_miles/zip_codes_in_area with it"
        },
        "specialties": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "specialties searched"
        },
        "specialties_note": {
          "type": "string"
        },
        "patient": {
          "type": "string"
        },
        "medicare_patient": {
          "type": "string"
        },
        "narrower_terms_included": {
          "type": "integer",
          "description": "how many narrower MeSH terms were searched too"
        },
        "broader_terms_included": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "broader MeSH terms also searched"
        },
        "specialty_fit_basis": {
          "type": "string"
        },
        "patient_mix_categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "prescribing_categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "language": {
          "type": [
            "string",
            "object"
          ]
        },
        "specialty_fit": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "specialty_id": {
                "type": "string"
              },
              "share_of_doctors_with_this_focus_pct": {
                "type": "integer"
              }
            }
          }
        },
        "left_out": {
          "type": "string"
        }
      },
      "description": "how the request was read; check it matches what the person asked. Other keys may appear"
    },
    "total_matches": {
      "type": "integer"
    },
    "offset": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DoctorListing"
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "next_step": {
      "type": "string"
    }
  },
  "required": [
    "results"
  ],
  "$defs": {
    "DoctorListing": {
      "type": "object",
      "properties": {
        "rank": {
          "type": "integer"
        },
        "doctor_id": {
          "type": "string",
          "pattern": "^dr_[0-9a-z]{12}$",
          "description": "use with get_doctor"
        },
        "name": {
          "type": "string"
        },
        "degree": {
          "type": "string",
          "description": "e.g. MD, DO"
        },
        "npi": {
          "type": "string",
          "description": "10-digit NPI"
        },
        "specialty": {
          "type": "string"
        },
        "specialty_source": {
          "type": "string"
        },
        "hospital_website_specialties": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "site": {
                "type": "string"
              },
              "specialties": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "description": "departments listed on the doctor's hospital website (up to 2 sites)"
        },
        "listed_on_childrens_hospital_website": {
          "type": "boolean"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "distance_miles": {
          "type": "number",
          "description": "from the searched place, when searching near a place"
        },
        "match_basis": {
          "type": "string",
          "enum": [
            "direct_evidence",
            "specialty_fit",
            "other"
          ],
          "description": "why this doctor matched a condition or procedure"
        },
        "procedure_volume_2024": {
          "type": "string",
          "description": "present when the need maps to a procedure group and this doctor has no published Medicare count for it: either CMS hid a count under 11 patients, or the doctor has no 2024 Medicare fee-for-service record. Unknown, not zero."
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "e.g. excluded from federal programs, opted out of Medicare"
        },
        "detail_has": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "which kinds of evidence get_doctor will show for this doctor (not the evidence itself), e.g. listed_focus_areas, procedure_volume_for_this_need, phone, languages"
        }
      },
      "required": [
        "rank",
        "doctor_id",
        "name"
      ]
    },
    "Provider": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string"
        },
        "data_version": {
          "type": "string",
          "description": "database version, e.g. public-2026-10-12.2"
        }
      }
    }
  }
}