> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hospitals

> List the hospitals registered with Medicare in a US ZIP code, with address, type, owner, emergency services and overall quality rating.

List the hospitals registered with Medicare in a US ZIP code, from the hospital list of the US Centers for Medicare & Medicaid Services. Each hospital has its name, address, county, published main telephone line, type, ownership, whether it has emergency services and its overall quality rating from 1 to 5. The rating is null when the source gives no number for the hospital. A ZIP code with no registered hospital gives a total of 0 and an empty list. The total is the number of hospitals in the ZIP code, which can be more than the number returned.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="zip_code" type="string" required>
  A five-digit US ZIP code, for example 45220. zip\_code must be five digits.
</ParamField>

<ParamField body="limit" type="integer">
  The most hospitals to return. Default 10. From 1 to 25. Defaults to `10`.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `place_hospitals`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US Centers for Medicare & Medicaid Services`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.total" type="number">
  How many hospitals the source lists in the ZIP code.
</ResponseField>

<ResponseField name="data.result.hospitals" type="object[]">
  The hospitals in the ZIP code, up to the limit. Empty when none is registered.
</ResponseField>

<ResponseField name="data.result.hospitals[].facility_id" type="string">
  The hospital's Medicare provider number.
</ResponseField>

<ResponseField name="data.result.hospitals[].name" type="string">
  The hospital's name.
</ResponseField>

<ResponseField name="data.result.hospitals[].address" type="string">
  Street address.
</ResponseField>

<ResponseField name="data.result.hospitals[].city" type="string">
  City or town.
</ResponseField>

<ResponseField name="data.result.hospitals[].state" type="string">
  Two-letter state code.
</ResponseField>

<ResponseField name="data.result.hospitals[].zip_code" type="string">
  ZIP code.
</ResponseField>

<ResponseField name="data.result.hospitals[].county" type="string">
  County or parish.
</ResponseField>

<ResponseField name="data.result.hospitals[].phone" type="string">
  The hospital's published main telephone line.
</ResponseField>

<ResponseField name="data.result.hospitals[].type" type="string">
  Kind of hospital, for example Acute Care Hospitals.
</ResponseField>

<ResponseField name="data.result.hospitals[].ownership" type="string">
  Who owns the hospital, for example Voluntary non-profit - Private.
</ResponseField>

<ResponseField name="data.result.hospitals[].emergency_services" type="boolean">
  Whether the hospital has emergency services, or null when the source gives no answer.
</ResponseField>

<ResponseField name="data.result.hospitals[].overall_rating" type="number">
  Overall quality rating from 1 to 5, or null when the source gives no number.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/lookup/place-hospitals \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "zip_code": "45220",
      "limit": 2
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/place-hospitals", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "zip_code": "45220",
      "limit": 2
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('lookup/place-hospitals', {
    zip_code: '45220',
    limit: 2
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "place_hospitals",
      "result": {
        "total": 2,
        "hospitals": [
          {
            "facility_id": "36003F",
            "name": "CINCINNATI VA MEDICAL CENTER",
            "address": "3200 VINE STREET",
            "city": "CINCINNATI",
            "state": "OH",
            "zip_code": "45220",
            "county": "HAMILTON",
            "phone": "(513) 861-3100",
            "type": "Acute Care - Veterans Administration",
            "ownership": "Veterans Health Administration",
            "emergency_services": true,
            "overall_rating": 4
          },
          {
            "facility_id": "360134",
            "name": "GOOD SAMARITAN HOSPITAL",
            "address": "375 DIXMYTH AVENUE",
            "city": "CINCINNATI",
            "state": "OH",
            "zip_code": "45220",
            "county": "HAMILTON",
            "phone": "(513) 862-2601",
            "type": "Acute Care Hospitals",
            "ownership": "Voluntary non-profit - Private",
            "emergency_services": true,
            "overall_rating": 4
          }
        ]
      },
      "evidence": {
        "source": "US Centers for Medicare & Medicaid Services",
        "source_kind": "public",
        "retrieved_at": "2026-10-13T12:00:00.000Z",
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.005 per lookup. See [Pricing](/pricing) for every tool.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.