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

> Search for homes for sale across UK cities on Properstar and instantly access detailed property information including prices, photos, bedroom and bathroom counts, square footage, and exact locations. Find your next home with comprehensive listings that show you everything you need to know at a glance.

**Category:** Real Estate | **Website:** [www.properstar.co.uk/mexico/cancun/buy/apartment-house](https://www.properstar.co.uk/mexico/cancun/buy/apartment-house) | **Docs:** [parse.bot/marketplace/0cfc12a5-c087-4b71-a901-8593a78ec20a/properstar-co-uk-api](https://parse.bot/marketplace/0cfc12a5-c087-4b71-a901-8593a78ec20a/properstar-co-uk-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-properstar-co-uk-api-0cfc12a5/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_brokers

Get a deduplicated list of broker/brokerage names active in a specified city. Internally fetches up to 2000 listings from the search API and extracts unique advertiser names. The Azure WAF JS challenge is solved automatically, adding ~2 seconds latency. Returns brokers sorted alphabetically.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | Yes | City slug for the search URL (e.g. 'cancun', 'playa-del-carmen', 'tulum'). Use lowercase with hyphens for multi-word cities. |
| `country` | string | No | Country slug for the search URL (e.g. 'mexico', 'spain', 'france'). Use lowercase with hyphens. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-properstar-co-uk-api-0cfc12a5/get_brokers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","country":"<string>"}'
```

### get_listing

Retrieve full property details for a single listing by its numeric ID. Returns structured data including price with multi-currency values, room counts, full photo gallery, location with coordinates, area measurements, contact information, full description text, and advertiser name. The Azure WAF JS challenge is solved automatically on each request, adding ~2 seconds latency. Returns stale_input when the listing ID does not exist (404/410 from upstream).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | integer | Yes | Numeric listing ID (e.g. from search_homes results). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-properstar-co-uk-api-0cfc12a5/get_listing \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<integer>"}'
```

### search_homes

Search apartments and houses for sale in a specified country and city across Properstar's international listings (covering Spain, France, and other countries worldwide). Returns paginated results with property details including price, listing URL, pictures, bedroom/bathroom count, size in square feet, text location, and latitude/longitude coordinates. Each page returns up to 1000 listings. The upstream API limits total retrievable results to 2000 (effectively 2 pages of 1000 each). The Azure WAF JS challenge is solved automatically on each request, adding ~2 seconds latency. Transient upstream 502 errors and WAF blocks are retried before surfacing a failure. Returns stale_input when the requested page is beyond the retrievable window.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | Yes | City slug for the search URL (e.g. 'cancun', 'playa-del-carmen', 'barcelona'). Use lowercase with hyphens for multi-word cities. |
| `country` | string | No | Country slug for the search URL (e.g. 'mexico', 'spain', 'france'). Use lowercase with hyphens. |
| `page` | integer | No | Page number for pagination (1-based). Each page returns up to 1000 listings. The API caps total retrievable results at 2000, so only pages 1 and 2 return data for most searches. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-properstar-co-uk-api-0cfc12a5/search_homes \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","country":"<string>","page":"<integer>"}'
```

### search_homes_filtered

Search apartments and houses for sale with optional filters for price, bedrooms, bathrooms, property type, and size. Works like search_homes but accepts additional filter parameters. All filters are optional — omitting any filter means no restriction for that field. Each page returns up to 1000 listings. The upstream API limits total retrievable results to 2000. The Azure WAF JS challenge is solved automatically on each request, adding ~2 seconds latency. Returns stale_input when the requested page is beyond the retrievable window.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | Yes | City slug for the search URL (e.g. 'cancun', 'playa-del-carmen', 'barcelona'). Use lowercase with hyphens for multi-word cities. |
| `country` | string | No | Country slug for the search URL (e.g. 'mexico', 'spain', 'france'). Use lowercase with hyphens. |
| `max_bathrooms` | integer | No | Maximum number of bathrooms. Omit for no upper bathroom bound. |
| `max_bedrooms` | integer | No | Maximum number of bedrooms. Omit for no upper bedroom bound. |
| `max_price` | number | No | Maximum asking price in GBP. Omit for no upper price bound. |
| `max_size_sqft` | number | No | Maximum property living area in square feet. Omit for no upper size bound. |
| `min_bathrooms` | integer | No | Minimum number of bathrooms. Omit for no lower bathroom bound. |
| `min_bedrooms` | integer | No | Minimum number of bedrooms. Omit for no lower bedroom bound. |
| `min_price` | number | No | Minimum asking price in GBP. Omit for no lower price bound. |
| `min_size_sqft` | number | No | Minimum property living area in square feet. Omit for no lower size bound. |
| `page` | integer | No | Page number for pagination (1-based). Each page returns up to 1000 listings. The API caps total retrievable results at 2000, so only pages 1 and 2 return data for most searches. |
| `property_type` | string | No | Filter by property type (e.g. 'apartment', 'house'). Case-insensitive. Omit to include both apartments and houses. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-properstar-co-uk-api-0cfc12a5/search_homes_filtered \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>","country":"<string>","max_bathrooms":"<integer>","max_bedrooms":"<integer>","max_price":"<number>","max_size_sqft":"<number>","min_bathrooms":"<integer>","min_bedrooms":"<integer>","min_price":"<number>","min_size_sqft":"<number>","page":"<integer>","property_type":"<string>"}'
```