# Census — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Get detailed property and housing statistics from the US Census Bureau, including home values, rental prices, occupancy rates, and housing unit counts across different geographic regions. Search and retrieve specific housing data tables to analyze real estate trends and demographics for your area of interest.

**Category:** Government & Public Data | **Website:** [www.census.gov/](https://www.census.gov/) | **Docs:** [parse.bot/marketplace/92e4c344-a52f-4927-9ebb-8a9ff2463564/census-gov-api](https://parse.bot/marketplace/92e4c344-a52f-4927-9ebb-8a9ff2463564/census-gov-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/census/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get property data

Get property and housing statistics for a specified geography. Returns median home value, median rent, owner/renter occupancy, housing unit counts, median year built, median rooms, household income, and monthly housing costs from ACS data. Makes multiple requests to Census data tables and merges results by geography. For state-level queries with geo_code=*, returns all 52 states/territories.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `county_code` | string | No | 3-digit county FIPS code. Required for tract queries. |
| `dataset` | string | No | ACS dataset: acs/acs5 (5-year estimates, all geographies) or acs/acs1 (1-year estimates, larger areas only). |
| `geo_code` | string | No | FIPS code for the geography, or * for all entities at the specified geo_level. |
| `geo_level` | string | No | Geography level. Accepted values: state, county, place, zip, tract. |
| `state_code` | string | No | 2-digit state FIPS code. Required for place and tract queries; optional for county queries to filter within a state. |
| `year` | string | No | ACS data year. Omitted, the scraper uses 2022, which is not the newest. The newest 5-year data (acs/acs5) is for two years before the current year, or the previous year from mid-December; the newest 1-year data (acs/acs1) is for the previous year from mid-September. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/census/get-property-data \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"county_code":"<string>","dataset":"<string>","geo_code":"<string>","geo_level":"<string>","state_code":"<string>","year":"<string>"}'
```

### Get table variables

Get all variables (columns) for a specific Census data table. Use this to discover available data fields before querying with get_property_data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `dataset` | string | No | ACS dataset: acs/acs5 or acs/acs1. |
| `table_id` | string | No | Census table ID (e.g. B25077 for Median Value, B25001 for Housing Units). Discoverable via search_property_tables. |
| `year` | string | No | ACS data year. Omitted, the scraper uses 2022, which is not the newest. The newest 5-year data (acs/acs5) is for two years before the current year, or the previous year from mid-December; the newest 1-year data (acs/acs1) is for the previous year from mid-September. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/census/get-table-variables \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"dataset":"<string>","table_id":"<string>","year":"<string>"}'
```

### Search property tables

Search for available Census data tables by keyword. Returns matching table IDs and descriptions from the ACS groups catalog. Useful for discovering additional property/housing data tables beyond the default set.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `dataset` | string | No | ACS dataset: acs/acs5 or acs/acs1. |
| `query` | string | No | Search keyword to filter tables by description or table ID (case-insensitive substring match). |
| `year` | string | No | ACS data year. Omitted, the scraper uses 2022, which is not the newest. The newest 5-year data (acs/acs5) is for two years before the current year, or the previous year from mid-December; the newest 1-year data (acs/acs1) is for the previous year from mid-September. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/census/search-property-tables \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"dataset":"<string>","query":"<string>","year":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.