openapi: 3.0.3
info:
  title: Garner Health Facilities Providers API
  version: v1.11.0
  license:
    name: Commercial
    url: https://getgarner.com
  description: "Garner's APIs power its core provider recommendation experience. These recommendations are based on over 60 billion\nanonymized health insurance claims that paint a clear picture of a patient's journey through the healthcare system. \n\nUsing these data, Garner evaluates whether physicians practice evidence-based medicine as defined by major,\nrespected healthcare journals. Garner has designed over 550 clinical and financial metrics that look closely\nat every decision a physician makes rather than relying on standard industry episode groupers. This results in\nrankings that are much more transparent and trustworthy and enable better-informed decisions for patients,\nphysicians, and payers.\n\n# Authentication: \n  \n## OAuth2.0\n\n*If you were provided a JWT at account setup rather than an API client id and client secret, please refer to instructions for [legacy token authentication.](#section/Authentication:/Legacy-token)*\n\nGarner APIs authenticate with OAuth 2.0 access tokens. You will be provided an API client ID and API client secret during account setup. \nThe client ID and client secret can be exchanged for an access token which in turn authenticates your app when making calls to Garner's APIs. \n\nTo obtain an access token, make a request to the `POST oauth2/token/` endpoint. In the request body, include the `client_id`, `client_secret`, \nand `grant_type=client_credentials`. This response will contain an `access_token`, the `token_type` which will always be \"Bearer\", \nand `expires_in` which is the lifetime in seconds of the token. \n\nThe access token can be used to authenticate with Garner's APIs. When making a request, provide the access token as a \nbearer token in the `Authorization` header. \n\nFor example, \n\n**JavaScript**\n```js\n/* Get the token */\nconst { access_token, token_type, expires_in } = await fetch('https://api.getgarner.com/oauth2/token', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n  body: new URLSearchParams({\n    grant_type: 'client_credentials',\n    client_id: '<YOUR_API_CLIENT_ID_HERE>',\n    client_secret: '<YOUR_API_CLIENT_SECRET_HERE>',\n  }),\n}).then(r => r.json());\n\n\n/* Use the token */\nconst { providers } = fetch(\n  'https://api.getgarner.com/providers',\n  {\n    method: 'GET',\n    headers: {'Authorization': `Bearer ${<YOUR_ACCESS_TOKEN_HERE>}`},\n    query: ...\n  },\n).then(response => response.json());\n\n``` \n**cURL**\n```sh\n# Get the token\ncurl --location 'https://api.garner.health/oauth2/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'client_id=<YOUR_API_CLIENT_ID_HERE' \\\n--data-urlencode 'client_secret=<YOUR_API_CLIENT_SECRET_HERE>'\n\n# Use the token\ncurl -G https://api.getgarner.com/providers -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>'\n```\n\n\n### Managing the access token\nThe access token will only be valid for 15 minutes. We recommend caching the token in your application so that it can be reused up to its expiration. This can be managed by the app programmatically by implementing a `GarnerTokenClient` class like the following:\n```typescript\nclass GarnerTokenClient {\n  /** Cached access token */\n  private currentToken: string | undefined;\n  /** Time at which the cached token expires */\n  private expirationTime: number | undefined;\n\n  /** \n  *  Fetches a new access token from the `POST /oauth2/token` endpoint,\n  *  then caches the token and its expiration time.\n  *  Returns a promise that resolves to the newly fetched access token\n  */\n  private async fetchNewToken(): Promise<string> {\n    const currentTime = Date.now();\n    const { access_token: accessToken, expires_in: expiresIn } = await fetch('https://api.getgarner.com/oauth2/token', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n      body: new URLSearchParams({\n        grant_type: 'client_credentials',\n        client_id: '<YOUR_API_CLIENT_ID_HERE>',\n        client_secret: '<YOUR_API_CLIENT_SECRET_HERE>',\n      }),\n    }).then(r => r.json());\n    // Cache the access token\n    this.currentToken = accessToken;\n    // Set the expiration time as the current time plus the number of ms until the token expires. Subtract a 15 second buffer to account for lag.\n    this.expirationTime = (currentTime + expiresIn * 1000) - 15000; \n    return accessToken;\n  }\n\n  /** \n  *  Returns the cached access token if it is valid. \n  *  Otherwise, fetches a new token.\n  */\n  async getToken(): Promise<string> {\n    if (this.currentToken && this.expirationTime && Date.now() < this.expirationTime) {\n      return this.currentToken;\n    }\n    return await this.fetchNewToken();\n  }\n}\n```\n\nThen when making a request to Garner's APIs you can use the response of `getToken()` from an instance of the `GarnerTokenClient` class as your token.\n\nFor example, \n\n```typescript\nconst garnerTokenClient = new GarnerTokenClient();\n\nfetch('https://api.getgarner.com/providers',\n  {\n    method: 'GET',\n    headers: {'Authorization': `Bearer ${await garnerTokenClient.getToken()}`},\n    query: ...\n  },\n);\n\n```\n## Legacy token\n\n*If you were provided an API client id and client secret at account setup rather than a token, please refer to instructions for [OAuth2.0 authentication.](#section/Authentication:/OAuth2.0)*\n\nAuthenticating is done with an JSON Web Token (JWT) provided as a `Bearer` token to the `Authorization` header.\nYou will have received a token during account setup.\n\nFor example, \n```sh\ncurl -G https://api.getgarner.com -H 'Authorization: Bearer <YOUR_API_TOKEN_HERE>'\n```\n"
servers:
- url: https://api.getgarner.com
security:
- ApiToken: []
tags:
- name: Providers
paths:
  /providers:
    parameters:
    - $ref: '#/components/parameters/acceptVersion'
    - name: Request-ID
      in: header
      schema:
        type: string
      required: false
      description: Correlation ID to be provided on responses
    get:
      operationId: GetRankedProviders
      summary: Get a list of providers near a position
      x-codeSamples:
      - lang: curl
        source: "curl -i -X GET \\\n  'https://api.getgarner.com/providers?gender=male&language=fas&lat=40.8144984&limit=30&lng=-74.259863&networkId=string&plan=core&specialty=adult_general_gastroenterologist' \\\n  -H 'Accept-Version: 1' \\\n  -H 'Authorization: Bearer <YOUR_API_TOKEN_HERE>' \\\n  -H 'Request-ID: string'\n"
      - lang: JavaScript
        source: "const query = new URLSearchParams({\n  gender: 'male',\n  language: 'fas',\n  lat: '40.8144984',\n  lng: '-74.259863',\n  limit: '30',\n  networkId: 'string',\n  plan: 'core',\n  specialty: 'adult_general_gastroenterologist'\n}).toString();\n\nconst resp = await fetch(\n  `https://api.getgarner.com/providers?${query}`,\n  {\n    method: 'GET',\n    headers: {\n      'Accept-Version': '1',\n      'Request-ID': 'string',\n      Authorization: 'Bearer <YOUR_API_TOKEN_HERE>'\n    }\n  }\n);\n\nconst data = await resp.text();\nconsole.log(data);\n"
      description: "This endpoint supports two modes of querying. Depending on the query parameter you provide, a different result\nwill be returned.\n\n| Query Parameter | Search Mode | Query Type | Result Type |\n| -- | -- | -- | -- |\n| `specialty` | Ranked Search | `RankedProviderQuery` | `RankedProviderList` |\n| `name` | Directory Search | `DirectorySearchQuery` | `DirectorySearchResultList` |\n| `npi` | Directory Search | `DirectorySearchQuery` | `DirectorySearchResultList` |\n\n\n### Ranked Search (Primary)\n\nPerforms a ranked query for a specialty near a specific `Position`. This will return \nresults in rank-order, where the first `Provider` in the list is the most highly recommended based on distance, \nquality, cost, and patient reviews.\n\n### Directory Search (Secondary)\n\nPerforms a lookup for a professional by name or NPI near a specific Position; facilities are not currently \nsupported. **This will return results by relevance to the query. Providers returned are not necessarily\nrecommended by Garner.**\n"
      parameters:
      - name: QueryModeParams
        in: query
        explode: true
        schema:
          oneOf:
          - $ref: '#/components/schemas/RankedProviderQuery'
          - $ref: '#/components/schemas/DirectorySearchQuery'
      responses:
        '200':
          description: Providers resolved successfully
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RankedProviderList'
                - $ref: '#/components/schemas/DirectorySearchResultList'
        '422':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
      tags:
      - Providers
components:
  schemas:
    WorkingHours:
      description: The days and times of day the provider's office is open
      type: object
      properties:
        day:
          $ref: '#/components/schemas/DayOfWeek'
        open:
          type: number
          description: The time of day the office opens. Represented as minutes after midnight
        close:
          type: number
          description: The time of day the office closes. Represented as minutes after midnight
    DirectorySearchQuery:
      allOf:
      - type: object
        properties:
          name:
            type: string
            description: Name or partial name of the provider. Must not be combined with `npi`
            example: Mark Smith
          npi:
            format: '[0-9]{9}'
            type: string
            description: The unique identifier for the provider. Must not be combined with `name`
            example: 123456789
          networkId:
            type: string
            description: "When included, the `networkStatus` attribute of the result will indicate whether the physician is \nin-network with the given network.\n"
          gender:
            type: string
            enum:
            - male
            - female
            description: Filters results to a given gender. If omitted, no gender filter will be applied.
          language:
            type: string
            description: Filters results to require a given language to be spoken by the provider. If omitted, no language filter will be applied. Must be provided as a [ISO639-3](https://iso639-3.sil.org/code_tables/639/data) code.
            example: fas
        required:
        - networkId
      - $ref: '#/components/schemas/BaseQuery'
    DirectorySearchResultList:
      type: object
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/ProviderDirectoryEntry'
          description: The result list of professionals for the request.
      required:
      - providers
    Location:
      description: The office location of a provider
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for this location
        name:
          type: string
          description: Name of the office or facility for the associated location and provider. Only returned if provider is a professional rather than a facility
        providerCorporationName:
          type: string
          description: The primary provider corporation (e.g. health system) affiliated with this location. When both `providerCorporationName` and `allProviderCorporations` are present, the value here is also included in `allProviderCorporations`. Only returned when the provider is a professional and the corporation is known.
          example: NYU Langone Health
        allProviderCorporations:
          type: array
          items:
            type: string
          description: All provider corporations (e.g. health systems) the professional is affiliated with at this location. When `providerCorporationName` is also returned, it is the primary entry in this list. Only returned when the provider is a professional and at least one affiliation is known.
          example:
          - NYU Langone Health
          - Mount Sinai Health System
        lines:
          type: array
          items:
            type: string
          description: The lines of an address, in order
        city:
          type: string
          description: The city of the address
        state:
          type: string
          description: The state of the address
        position:
          $ref: '#/components/schemas/Position'
      required:
      - lines
      - city
      - state
      - zipCode
      - position
      additionalProperties: false
    ServiceError:
      type: object
      properties:
        requestId:
          type: number
        message:
          type: string
        data:
          type: object
          additionalProperties: true
      required:
      - message
      additionalProperties: false
    Gender:
      type: string
      enum:
      - male
      - female
      description: Gender. Only returned if provider is a professional rather than a facility
    RankedProviderQuery:
      allOf:
      - type: object
        properties:
          specialty:
            type: string
            description: Specialty code to query.
            example: adult_general_gastroenterologist
          networkId:
            type: string
            description: Filters results to a given carrier network when included.
          gender:
            type: string
            enum:
            - male
            - female
            description: Filters results to a given gender. If omitted, no gender filter will be applied.
          language:
            type: string
            description: Filters results to require a given language to be spoken by the provider. If omitted, no language filter will be applied. Must be provided as a [ISO639-3](https://iso639-3.sil.org/code_tables/639/data) code.
            example: fas
        required:
        - networkId
      - $ref: '#/components/schemas/BaseQuery'
    RankedProviderList:
      type: object
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/RankedProvider'
          description: The result list of providers (professionals or facilities) for the request. The providers are in rank order.
      required:
      - providers
    BaseQuery:
      type: object
      properties:
        lat:
          type: number
          description: Latitude of the origin of the query. Must be combined with `lng`. Must not be combined with `zipCode`
          example: 40.8144984
        lng:
          type: number
          description: Longitude of the origin of the query. Must be combined with `lat`. Must not be combined with `zipCode`
          example: -74.259863
        zipCode:
          format: '[0-9]{5}'
          type: string
          description: The center of this ZIP-5 code to use as the origin of the query. Must not be combined with `lat` or `lng`
          example: '10451'
        plan:
          type: string
          description: The data subscription plan associated with your account. Contact your account manager for the correct value to this parameter.
          example: core
        limit:
          type: number
          description: The maximum number of providers to include in the response. Defaults to 15.
          example: 15
          maximum: 30
          default: 15
      required:
      - plan
    DayOfWeek:
      type: number
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      description: ISO day of week (e.g. 1 is Monday)
    Position:
      description: Global coordinates
      type: object
      properties:
        lat:
          type: number
          description: Latitude
        lng:
          type: number
          description: Longitude
      required:
      - lat
      - lng
      additionalProperties: false
    RankedProvider:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the provider
        npi:
          type: string
          description: National Provider Identifier
        firstName:
          type: string
          description: First name of the provider. Only returned if provider is a professional rather than a facility
        lastName:
          type: string
          description: Last name of the provider. Only returned if provider is a professional rather than a facility
        credentials:
          type: string
          description: Degrees and certifications held by the provider. Only returned if provider is a professional rather than a facility
          example: MD
        gender:
          $ref: '#/components/schemas/Gender'
        specialty:
          type: string
          description: The specialty identifier for the provider
          example: adult_general_gastroenterologist
        organizationName:
          type: string
          description: Name of the facility. Only returned if provider is a facility rather than a professional
          example: Mount Sinai
        languages:
          type: array
          items:
            type: string
            format: '[a-z]{3}'
          description: List of languages spoken by the provider. Languages are [ISO639-3](https://iso639-3.sil.org/code_tables/639/data) codes. Only returned if provider is a professional rather than a facility,
        metrics:
          description: Relevant metrics for the query. Will be repeated for each provider ranked for ease of comparison.
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Metric descriptor
                example: id="Patient Outcomes"
              value:
                type: string
                enum:
                - good
                - very_good
                - excellent
                description: Performance on the metric. Providers will only be recommended by the API if they have at least a score of `good` on each metric
        overallScore:
          description: Score for the provider taking into account overall quality and cost
          type: integer
          minimum: 0
          maximum: 100
        reviewStars:
          description: Star-rating synthesizing the patient reviews for the provider
          type: number
          minimum: 1
          maximum: 5
        location:
          $ref: '#/components/schemas/Location'
        hours:
          type: array
          items:
            $ref: '#/components/schemas/WorkingHours'
        phoneNumber:
          type: string
          format: '[0-9]{10}'
          description: 10-digit phone number
          example: 5555555555
        faxNumber:
          type: string
          format: '[0-9]{10}'
          description: 10-digit fax number
          example: 5555555555
        distanceMi:
          type: number
          description: The driving distance to the location in miles
      required:
      - costScore
      - distanceMi
      - id
      - location
      - phoneNumber
      - specialty
      additionalProperties: false
      description: A ranked provider
      example:
        id: p.f3ac4f1a01275ca68e6c932ad4722491
        npi: 1231766309
        firstName: Sepideh
        lastName: Baghian
        credentials: MD
        gender: female
        specialty: adult_general_gastroenterologist
        languages:
        - eng
        - fas
        metrics:
        - id: accurately_diagnoses_gi_issues
          value: very_good
        - id: performs_safe_colonoscopies
          value: excellent
        - id: great_patient_outcomes
          value: good
        overallScore: 92
        reviewStars: 4.5
        location:
          id: fc8b2f21-506c-5c7c-a96f-a4580bd9ba87
          name: Mount Sinai Morningside Cardiovascular Institute
          providerCorporationName: Mount Sinai Health System
          allProviderCorporations:
          - Mount Sinai Health System
          - NYC Health + Hospitals
          city: New York
          lines:
          - 440 W 114th St 2nd Fl Ste 220
          position:
            lat: 40.8053
            lng: -73.9618
          state: NY
          zipCode: '10025'
        hours:
        - day: 1
          open: 480
          close: 1020
        - day: 2
          open: 480
          close: 1020
        - day: 3
          open: 480
          close: 1020
        - day: 4
          open: 480
          close: 1020
        - day: 5
          open: 480
          close: 1020
        phoneNumber: '2124271540'
        faxNumber: '2124107196'
        distanceMi: 3.50453352288
    ProviderDirectoryEntry:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the provider
        npi:
          type: string
          description: National Provider Identifier
        firstName:
          type: string
          description: First name of the provider.
        lastName:
          type: string
          description: Last name of the provider.
        credentials:
          type: string
          description: Degrees and certifications held by the provider. Only returned if provider is a professional rather than a facility
          example: MD
        gender:
          $ref: '#/components/schemas/Gender'
        specialty:
          type: string
          description: The specialty identifier for the provider
          example: adult_general_gastroenterologist
        networkStatus:
          type: boolean
          description: Whether the doctor is in-network with the network specified in the query parameters
        languages:
          type: array
          items:
            type: string
            format: '[a-z]{3}'
          description: List of languages spoken by the provider. Languages are [ISO639-3](https://iso639-3.sil.org/code_tables/639/data) codes. Only returned if provider is a professional rather than a facility
        location:
          $ref: '#/components/schemas/Location'
        hours:
          type: array
          items:
            $ref: '#/components/schemas/WorkingHours'
        phoneNumber:
          type: string
          format: '[0-9]{10}'
          description: 10-digit phone number
          example: 5555555555
        faxNumber:
          type: string
          format: '[0-9]{10}'
          description: 10-digit phone number
          example: 5555555555
        distanceMi:
          type: number
          description: The driving distance to the location in miles
      required:
      - distanceMi
      - id
      - location
      - phoneNumber
      - specialty
      additionalProperties: false
      description: A ranked provider
      example:
        id: p.f3ac4f1a01275ca68e6c932ad4722491
        npi: 1231766309
        firstName: Sepideh
        lastName: Baghian
        credentials: MD
        gender: female
        specialty: adult_general_gastroenterologist
        languages:
        - eng
        - fas
        location:
          id: fc8b2f21-506c-5c7c-a96f-a4580bd9ba87
          name: Mount Sinai Morningside Cardiovascular Institute
          providerCorporationName: Mount Sinai Health System
          allProviderCorporations:
          - Mount Sinai Health System
          - NYC Health + Hospitals
          city: New York
          lines:
          - 440 W 114th St 2nd Fl Ste 220
          position:
            lat: 40.8053
            lng: -73.9618
          state: NY
          zipCode: '10025'
        hours:
        - day: 1
          open: 480
          close: 1020
        - day: 2
          open: 480
          close: 1020
        - day: 3
          open: 480
          close: 1020
        - day: 4
          open: 480
          close: 1020
        - day: 5
          open: 480
          close: 1020
        phoneNumber: '2124271540'
        faxNumber: '2124107196'
        distanceMi: 3.50453352288
        networkStatus: true
  parameters:
    acceptVersion:
      name: Accept-Version
      in: header
      required: true
      schema:
        type: integer
        enum:
        - 1
      description: The API major version.
  securitySchemes:
    ApiToken:
      type: http
      scheme: bearer
      bearerFormat: API_TOKEN