> ## 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.

# Place Resolve

> Resolve a US street address to its coordinates and its state, county and census tract codes.

Resolve a US street address to the matched address, its latitude and longitude, and the codes for its state, county and census tract (plus census block and incorporated place when the source has them). Use it first when another fact about a place is keyed by state and county, or by coordinates, so an agent does not have to guess them. Street addresses in the United States only: no post-office boxes, no place names or landmarks, no addresses outside the US. Give the whole address on one line, for example "1600 Pennsylvania Ave NW, Washington, DC". Only the best match is returned; `candidates` is how many matches the source offered. An address that matches nothing is a completed result with `found` false and every other field null.

## Authentication

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

## Request Body

<ParamField body="address" type="string" required>
  A US street address on one line, with city and state or ZIP, for example 1600 Pennsylvania Ave NW, Washington, DC. 5 to 200 characters.
</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_resolve`
</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 Census Bureau`.
</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.found" type="boolean">
  False when the source matched no address.
</ResponseField>

<ResponseField name="data.result.matched_address" type="string">
  The address as the source matched it, for example 1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.latitude" type="number">
  Latitude. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.longitude" type="number">
  Longitude. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.street" type="string">
  House number and street of the matched address. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.city" type="string">
  City. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.state" type="string">
  Two-letter state postal code. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.postal_code" type="string">
  Postal code. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.state_code" type="string">
  Two-digit state FIPS code, for example 11. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.county_code" type="string">
  Three-digit county FIPS code within the state, for example 001. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.county_name" type="string">
  County name. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.county_id" type="string">
  Five-digit county code (state + county), for example 11001. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.tract_id" type="string">
  Eleven-digit census tract code, for example 11001980000. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.block_id" type="string">
  Fifteen-digit census block code. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.place_name" type="string">
  The incorporated place (city, town) the address is in; null outside one.
</ResponseField>

<ResponseField name="data.result.candidates" type="number">
  How many matches the source offered; only the first is returned.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/resolve/place \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "address": "1600 Pennsylvania Ave NW, Washington, DC"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/resolve/place", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "address": "1600 Pennsylvania Ave NW, Washington, DC"
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('resolve/place', {
    address: '1600 Pennsylvania Ave NW, Washington, DC'
  });
  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_resolve",
      "result": {
        "found": true,
        "matched_address": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500",
        "latitude": 38.898702605245,
        "longitude": -77.035189204737,
        "street": "1600 PENNSYLVANIA AVE NW",
        "city": "WASHINGTON",
        "state": "DC",
        "postal_code": "20500",
        "state_code": "11",
        "county_code": "001",
        "county_name": "District of Columbia",
        "county_id": "11001",
        "tract_id": "11001980000",
        "block_id": "110019800001034",
        "place_name": "Washington city",
        "candidates": 1
      },
      "evidence": {
        "source": "US Census Bureau",
        "source_kind": "public",
        "retrieved_at": "2026-01-15T12:00:00.000Z",
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.002 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.