# Homestra Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/homestra/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/homestra-search |

## Description

Search Homestra property listings using a direct search URL with filters, returning structured results with prices, sizes, locations, and photos.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/homestra/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search houses for sale within price range

```json
[
  {
    "id": "0d45a754-0e49-4c35-b0b6-bf1dba0d47cd",
    "city": "Valderice",
    "size": 114,
    "slug": "spacious-3-bed-detached-home-with-sea-views-and-guest-studio-in-valderice-trapani",
    "type": "house",
    "price": 250000,
    "title": "Spacious 3-Bed Detached Home with Sea Views and Guest Studio in Valderice, Trapani",
    "status": "for_sale",
    "address": "Valderice, Trapani, Sicily, Italy",
    "location": {
      "type": "Point",
      "coordinates": [
        38.04061,
        12.62553
      ]
    },
    "lot_size": 800,
    "photo_url": "https://storage.googleapis.com/homestra-images/property-image-e4e958d4-fdc4-430c-a6e3-aee2cd7b6fd0-1721847180.jpg",
    "country_code": "it",
    "listing_date": "2024-07-25T22:26:03.577Z"
  },
  {
    "id": "41d7f3ef-6d42-4fb2-9ddf-1d07ea0d683f",
    "city": "Carvoeiro",
    "size": 330,
    "slug": "peaceful-3-bedroom-villa-with-panoramic-views-in-barroselas-portugal",
    "type": "house",
    "price": 349000,
    "title": "Peaceful 3-Bedroom Villa with Panoramic Views in Barroselas, Portugal",
    "status": "for_sale",
    "address": "Minho, Barroselas, Portugal",
    "location": {
      "type": "Point",
      "coordinates": [
        41.65043,
        -8.67458
      ]
    },
    "lot_size": 1673,
    "photo_url": "https://storage.googleapis.com/homestra-images/property-image-e4e958d4-fdc4-430c-a6e3-aee2cd7b6fd0-1721847180.jpg",
    "country_code": "pt",
    "listing_date": "2024-07-25T21:30:10.404Z"
  }
]
```

## Documentation

## Overview
The Homestra Search endpoint returns structured property listings from a Homestra search URL, including prices, sizes, locations, and photos.

## Quickstart
```
GET https://api.piloterr.com/v2/homestra/search?query=https://homestra.com/list/houses-for-sale/?maximum-price=900000%26minimum-price=75000%26page=1
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Valid Homestra search URL |

## Response fields
| Field | Type | Description |
|---|---|---|
| `[].title` | string | Listing title |
| `[].type` | string | Property type |
| `[].price` | number | Listed price |
| `[].size` | number | Living area in sqm |
| `[].country_code` | string | ISO country code |
| `[].slug` | string | Property slug |

## Notes
- URL-encode `&` as `%26`.
- Use `page=N` to paginate.

## Main use cases
- Build international real estate search tools for European property buyers
- Monitor Homestra listings by country, region, or price range
- Generate automated property alerts matching specific criteria
- Power investment analytics with structured Homestra listing data