# 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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-expatistan-com-api-8815f620/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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/parse-expatistan-com-api-8815f620/compare_cities \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-expatistan-com-api-8815f620/get_city_cost_of_living \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-expatistan-com-api-8815f620/get_city_rankings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-expatistan-com-api-8815f620/get_country_cost_of_living \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-expatistan-com-api-8815f620/get_country_rankings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-expatistan-com-api-8815f620/get_recent_data \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-expatistan-com-api-8815f620/search_city_autocomplete \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```