# Expatistan — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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.

> Compare cost of living across cities and countries worldwide, view rankings, and analyze expense data to make informed decisions about relocating or understanding living costs globally. Search for specific cities and access the latest pricing information on housing, food, transportation, and other essential expenses.

**Category:** Maps & Geospatial | **Website:** [expatistan.com/](https://expatistan.com/) | **Docs:** [parse.bot/marketplace/8815f620-855d-4496-878f-269973b01a58/expatistan-com-api](https://parse.bot/marketplace/8815f620-855d-4496-878f-269973b01a58/expatistan-com-api)

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

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/expatistan/`
**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

### Compare cities

Compare cost of living between two cities side by side. Returns a summary statement with the percentage difference and detailed item-by-item price comparison across categories. Prices are shown in each city's local currency with conversions where applicable.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city1_slug` | string | Yes | First city slug (e.g. 'london'). Use search_city_autocomplete to find valid slugs. |
| `city2_slug` | string | Yes | Second city slug (e.g. 'paris'). Use search_city_autocomplete to find valid slugs. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/expatistan/compare-cities \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"city1_slug":"<string>","city2_slug":"<string>"}'
```

### Get city cost of living

Get detailed cost of living data for a specific city. Returns itemized prices across categories (Food, Housing, Clothes, Transportation, Personal Care, Entertainment) and monthly cost estimates for a single person and a family of four. Each price item includes the item description and local-currency price string.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city_slug` | string | Yes | The city slug identifier (e.g. 'london', 'new-york-city', 'paris'). Use search_city_autocomplete to find valid slugs. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/expatistan/get-city-cost-of-living \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"city_slug":"<string>"}'
```

### Get city rankings

Get ranked list of cities by cost of living price index. Can be filtered by region. Returns cities ordered from most to least expensive with their rank, name, slug, and price index value (100 = Prague baseline).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `region` | string | No | Region filter for rankings. Accepted values: world, europe, north-america, latin-america, asia, middle-east, africa, oceania. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/expatistan/get-city-rankings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"region":"<string>"}'
```

### Get country cost of living

Get aggregated cost of living data for an entire country. Returns itemized prices across categories (Food, Housing, Clothes, Transportation, Personal Care, Entertainment) and monthly cost estimates. Use get_country_rankings to discover valid country slugs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_slug` | string | Yes | The country slug identifier (e.g. 'united-kingdom', 'united-states', 'france'). Use get_country_rankings to find valid slugs. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/expatistan/get-country-cost-of-living \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country_slug":"<string>"}'
```

### Get country rankings

Get ranked list of all countries by cost of living price index. Returns countries ordered from most to least expensive with their rank, name, slug, and price index value (100 = Prague baseline).

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/expatistan/get-country-rankings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get recent data

Get recent city comparisons and recently submitted prices from the homepage. Returns the latest comparison results (with text and URLs) and price submissions by users (as text descriptions with timestamps).

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/expatistan/get-recent-data \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Search city autocomplete

Search for cities by name to find their valid slugs. Returns matching cities with their handle (slug), display name, and two-letter country code. Results are ordered by relevance.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword for city name (e.g. 'london', 'new york'). |

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

## Next steps

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