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

> Access Terra Caribbean's real estate marketplace data programmatically. Search and filter property listings by location, parish, zoning, price, and amenities across Barbados, Grenada, St. Lucia, and Trinidad & Tobago. Retrieve full listing details, browse blog content by country, and calculate estimated mortgage payments.

**Category:** Real Estate | **Website:** [terracaribbean.com/](https://terracaribbean.com/) | **Docs:** [parse.bot/marketplace/f922a9aa-569e-4abd-9851-846f44448dc2/terracaribbean-com-api](https://parse.bot/marketplace/f922a9aa-569e-4abd-9851-846f44448dc2/terracaribbean-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-terracaribbean-com-api-f922a9aa/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### calculate_mortgage

Calculate estimated monthly mortgage payments based on loan amount, annual interest rate, and term length. Uses standard amortization formula. Returns monthly payment, total amount paid over the term, and total interest paid.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | number | Yes | Mortgage loan amount in dollars. |
| `rate` | number | Yes | Annual interest rate as a percentage (e.g. 5.5 for 5.5%). |
| `years` | integer | Yes | Length of mortgage in years. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-terracaribbean-com-api-f922a9aa/calculate_mortgage \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"<number>","rate":"<number>","years":"<integer>"}'
```

### get_amenities

Get list of available property amenities. These values can be used in the amenities filter of search_properties.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-terracaribbean-com-api-f922a9aa/get_amenities \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_blog_posts

List blog posts for a specific Caribbean location. Returns titles, URLs, publication dates, and text excerpts. Not all location slugs have blog categories; verified working values are 'barbados' and 'grenada'.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | No | Location name slug. Verified working values: 'barbados', 'grenada'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-terracaribbean-com-api-f922a9aa/get_blog_posts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>"}'
```

### get_locations

Get all supported Caribbean territories and their country codes. Returns the four locations covered by Terra Caribbean: Barbados, Grenada, Saint Lucia, and Trinidad & Tobago.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-terracaribbean-com-api-f922a9aa/get_locations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_parishes

Get list of parishes (administrative regions) for a country. These values can be used in the regions filter of search_properties. Each country has its own set of parishes.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | No | Country code for which to retrieve parishes. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-terracaribbean-com-api-f922a9aa/get_parishes \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"<string>"}'
```

### get_property_details

Retrieve full details for a single property listing by its URL. Returns title, formatted price, full description, photo gallery URLs, reference number, and office contact phone. The URL is typically obtained from search_properties results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL of the property listing page, as returned in search_properties results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-terracaribbean-com-api-f922a9aa/get_property_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### search_properties

Full-text and filtered search across Caribbean property listings. Returns paginated summaries sorted by price ascending. Each result includes listing_id, price, location, and property attributes. Pagination is manual via offset; each page returns up to `limit` items. Note: combining regions and amenities filters in one call may cause upstream server errors due to a known site limitation; use them separately for reliable results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amenities` | string | No | Comma-separated list of amenities to filter by (e.g. 'Beachfront,Pool'). Values from get_amenities endpoint. |
| `baths_min` | string | No | Minimum number of bathrooms. |
| `beds_min` | string | No | Minimum number of bedrooms. |
| `country_code` | string | No | Country code for the search territory. |
| `keyword` | string | No | Free-text search against property titles and descriptions. |
| `limit` | integer | No | Number of results per page. |
| `listing_type` | string | No | Whether to search properties for sale or rent. |
| `offset` | integer | No | Result offset for pagination. |
| `price_max` | string | No | Maximum price in USD. |
| `price_min` | string | No | Minimum price in USD. |
| `regions` | string | No | Comma-separated list of parishes or regions to filter by (e.g. 'St. James,Christ Church'). Values from get_parishes endpoint. |
| `zoning` | string | No | Property category filter. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-terracaribbean-com-api-f922a9aa/search_properties \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amenities":"<string>","baths_min":"<string>","beds_min":"<string>","country_code":"<string>","keyword":"<string>","limit":"<integer>","listing_type":"<string>","offset":"<integer>","price_max":"<string>","price_min":"<string>","regions":"<string>","zoning":"<string>"}'
```