# HouseSigma Nearby Listings API Documentation

Scrappa's `GET /api/housesigma/nearby` returns similar homes for sale near one HouseSigma listing.

## Input

Pass `id`, the listing id from search. The answer holds the `reference` listing (id, MLS number, address) and `listings`, a list of cards in the same shape as the search endpoint, so price, rooms, area, coordinates, status and brokerage are all there. Pass a card `id` to the listing endpoint for the full record.

## Limits

Only homes for sale are returned. HouseSigma's nearby rentals and sold homes are empty or masked for visitors who are not signed in, so they are not offered. Fewer than 10 similar homes are usual. An empty `listings` list is a real result.

- **Documentation:** [https://scrappa.co/docs/housesigma-api/housesigma_nearby](https://scrappa.co/docs/housesigma-api/housesigma_nearby)
- **API group:** HouseSigma API
- **Endpoint:** `GET https://scrappa.co/api/housesigma/nearby`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Listing id from search, for example ZxwR7Mj4Jve3KabB. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/housesigma/nearby?id=ZxwR7Mj4Jve3KabB"
```

## Example response

```json
{
    "success": true,
    "listing_id": "ZxwR7Mj4Jve3KabB",
    "reference": {
        "id": "ZxwR7Mj4Jve3KabB",
        "ml_num": "W13861182",
        "address": "39 Exeter Street"
    },
    "returned": 1,
    "listings": [
        {
            "id": "ZxwR7Mj4Jve3KabB",
            "ml_num": "W13861182",
            "url": "https://housesigma.com/on/toronto-real-estate/39-exeter-street/home/0A9X3jP8xJEyvgxV/",
            "address": "39 Exeter Street",
            "price": {
                "amount": 930000,
                "currency": "CAD",
                "abbr": "0.93M",
                "gated": false
            },
            "bedrooms": 3,
            "bedrooms_extra": 1,
            "bathrooms": 2,
            "parking": {
                "total": 2,
                "garage": 2,
                "garage_type": "Detached",
                "text": "Detached 2 garage,  2 parking"
            },
            "property_type": {
                "code": "S.",
                "label": "Semi-Detached"
            },
            "style": "2-Storey",
            "area": {
                "text": "1100-1500",
                "min": 1100,
                "max": 1500,
                "unit": "feet\u00b2"
            },
            "lot": {
                "front": 18,
                "depth": 110,
                "area": 1980,
                "unit": "feet"
            },
            "location": {
                "lat": 43.67327,
                "lon": -79.4558
            },
            "status": {
                "kind": "sale",
                "text": "For Sale",
                "code": "A",
                "live": true
            },
            "community": "Weston-Pellam Park",
            "municipality": "Toronto",
            "province": "ON",
            "postal_code": null,
            "listed_at": "2026-10-05",
            "updated_at": "2026-10-25",
            "days_on_site": 20,
            "photo": "https://cache-e15.housesigma.com/file/pix-treb/W13861182/e3665_1_1200.webp?7f6b4e72",
            "brokerage": "SUTTON GROUP REALTY SYSTEMS INC.",
            "estimate": null,
            "rent_yield": 4.1,
            "scores": {
                "school": 6,
                "rent": 7,
                "growth": 5
            },
            "tags": [
                "For Sale"
            ],
            "open_house_date": [],
            "data_source": "PROPTX",
            "gated": false
        }
    ],
    "meta": {
        "endpoint_family": "nearby",
        "billable": true,
        "attempts": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter is missing, unknown or unusable, for example `page` above 200. Unknown parameters are rejected, never ignored. Non-billable. |
| 503 | Upstream Unavailable | HouseSigma could not be reached after retries, answered with an error, or returned an unexpected answer (`upstream_unavailable`, `upstream_blocked`, `token_unavailable`, `upstream_changed`). Retryable and never billed. Clients are never rate limited. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)