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

# Home Price Index

> Look up the latest quarterly change in the FHFA House Price Index for a US state, metropolitan area or census division.

Returns the percent change over the latest quarter, one year, five years and since 1991 in the index of home values of the US Federal Housing Finance Agency, with its rank, for a US state, a metropolitan area by name, or a census division or the nation. It gives percent changes for the latest quarter, not prices or index levels.

This product uses FHFA Data but is neither endorsed nor certified by FHFA.

## Authentication

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

## Request Body

**state** `string`

A two-letter US state code, or DC, for example MI. One of `AL`, `AK`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DE`, `DC`, `FL`, `GA`, `HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MD`, `MA`, `MI`, `MN`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`, `WA`, `WV`, `WI`, `WY`.

**metro** `string`

Words of a metropolitan area name, for example Detroit or Ann Arbor. 2 to 80 characters.

**division** `string`

A US census division, or united\_states for the nation. One of `united_states`, `new_england`, `middle_atlantic`, `east_north_central`, `west_north_central`, `south_atlantic`, `east_south_central`, `west_south_central`, `mountain`, `pacific`.

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

## Response (200 OK)

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

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `place_home_price_index`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.evidence.source** `string`

The public body the data comes from. Always `US Federal Housing Finance Agency`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string | null`

When the source says the fact was last updated, or `null` when the source gives no date

## Result

Nested under `data.result`.

**data.result.found** `boolean`

Whether at least one area matched.

**data.result.geography** `string`

Which list was read.

**data.result.index** `string`

Which index the changes come from.

**data.result.ranked\_among** `number`

How many areas are in the source's list, so the rank can be read.

**data.result.areas** `object[]`

The matching areas in rank order, up to 10.

**data.result.areas\[].name** `string`

The area's name as the source writes it.

**data.result.areas\[].rank** `number | null`

Rank by one-year change, 1 for the largest rise; null for the nation.

**data.result.areas\[].change\_1\_quarter\_pct** `number | null`

Percent change over the latest quarter. `null` when the source gives no value.

**data.result.areas\[].change\_1\_year\_pct** `number | null`

Percent change over one year. `null` when the source gives no value.

**data.result.areas\[].change\_5\_year\_pct** `number | null`

Percent change over five years. `null` when the source gives no value.

**data.result.areas\[].change\_since\_1991\_pct** `number | null`

Percent change since 1991. `null` when the source gives no value.

**data.result.more** `boolean`

True when more than 10 metros matched.

**data.result.notice** `string`

The notice the source requires every answer to carry.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/place-home-price-index \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "state": "MI"
  }'
```

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

```typescript SDK theme={null}
const result = await agent.tool('lookup/place-home-price-index', {
  state: 'MI'
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "place_home_price_index",
    "result": {
      "found": true,
      "geography": "state",
      "index": "purchase-only, seasonally adjusted",
      "ranked_among": 51,
      "areas": [
        {
          "name": "Michigan",
          "rank": 14,
          "change_1_quarter_pct": 0.39,
          "change_1_year_pct": 3.8,
          "change_5_year_pct": 38.8,
          "change_since_1991_pct": 292.88
        }
      ],
      "more": false,
      "notice": "This product uses FHFA Data but is neither endorsed nor certified by FHFA."
    },
    "evidence": {
      "source": "US Federal Housing Finance Agency",
      "source_kind": "public",
      "retrieved_at": "2026-10-26T12:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-10-26T12:00:00.000Z"
        }
      ],
      "as_of": null
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* Give exactly one of `state`, `metro` or `division`. `metro` matches a substring of the source's metro name, case-insensitively; up to 10 matches are returned in rank order and `more` says whether others matched.
* The answer does not name the quarter; the source publishes it quarterly.
* State and division changes come from the purchase-only, seasonally adjusted index; metro changes from the all-transactions, not seasonally adjusted index. Rank 1 is the largest one-year rise among `ranked_among` areas.
* A value the source leaves blank (too few sales) is null. A metro matching nothing gives `found: false`.
* 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.