Piloterr Homestra API
The Homestra API from Piloterr — 2 operation(s) for homestra.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/piloterr-com:piloterr-com-homestra-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Piloterr API Reference Homestra API
description: Complete API reference documentation.
version: 1.0.0
servers:
- url: https://api.piloterr.com
description: API Server
tags:
- name: Homestra
paths:
/v2/homestra/search:
get:
summary: Homestra Search
description: 'Search Homestra property listings using a direct search URL with filters, returning structured results with prices, sizes, locations, and photos.
**Credit cost:** 1 credit per call'
operationId: get-homestra-search
security:
- ApiKeyAuth: []
parameters:
- name: query
in: query
required: true
description: "A valid Homestra search URL with optional filters.\n\n**Example:**\n\n https://homestra.com/list/houses-for-sale/?maximum-price=900000&minimum-price=75000&page=1\n\nYou can customize filters directly in the URL, including price range, property type, location, and page number.\n\n**Notes:**\n- URL-encode `&` as `%26` when passing the query in a GET request parameter.\n- Use `page=N` to paginate through results."
schema:
type: string
description: "A valid Homestra search URL with optional filters.\n\n**Example:**\n\n https://homestra.com/list/houses-for-sale/?maximum-price=900000&minimum-price=75000&page=1\n\nYou can customize filters directly in the URL, including price range, property type, location, and page number.\n\n**Notes:**\n- URL-encode `&` as `%26` when passing the query in a GET request parameter.\n- Use `page=N` to paginate through results."
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/is_async'
- $ref: '#/components/parameters/soft_fail'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
city:
type: string
size:
type: integer
slug:
type: string
type:
type: string
price:
type: integer
title:
type: string
status:
type: string
address:
type: string
location:
type: object
properties:
type:
type: string
coordinates:
type: array
items:
type: number
lot_size:
type: integer
photo_url:
type: string
country_code:
type: string
listing_date:
type: string
examples:
Search houses for sale within price range:
value:
- 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'
'400':
description: Bad Request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
'401':
description: Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidKey:
value:
error: Invalid API Key
planRateLimit:
value:
error: 'Rate limit exceeded: You''ve exceeded the per second rate limit on your subscription'
keyQuota:
value:
error: 'Rate limit exceeded for the API key: quota monthly'
'402':
description: Payment Required — your subscription or credit balance is insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment required
'500':
description: Internal Server Error — something went wrong on our side.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Error
tags:
- Homestra
post:
summary: Homestra Search
description: 'Search Homestra property listings using a direct search URL with filters, returning structured results with prices, sizes, locations, and photos.
**Credit cost:** 1 credit per call'
operationId: post-homestra-search
security:
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/is_async'
- $ref: '#/components/parameters/soft_fail'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
description: "A valid Homestra search URL with optional filters.\n\n**Example:**\n\n https://homestra.com/list/houses-for-sale/?maximum-price=900000&minimum-price=75000&page=1\n\nYou can customize filters directly in the URL, including price range, property type, location, and page number.\n\n**Notes:**\n- URL-encode `&` as `%26` when passing the query in a GET request parameter.\n- Use `page=N` to paginate through results."
required:
- query
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
city:
type: string
size:
type: integer
slug:
type: string
type:
type: string
price:
type: integer
title:
type: string
status:
type: string
address:
type: string
location:
type: object
properties:
type:
type: string
coordinates:
type: array
items:
type: number
lot_size:
type: integer
photo_url:
type: string
country_code:
type: string
listing_date:
type: string
examples:
Search houses for sale within price range:
value:
- 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'
'400':
description: Bad Request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
'401':
description: Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidKey:
value:
error: Invalid API Key
planRateLimit:
value:
error: 'Rate limit exceeded: You''ve exceeded the per second rate limit on your subscription'
keyQuota:
value:
error: 'Rate limit exceeded for the API key: quota monthly'
'402':
description: Payment Required — your subscription or credit balance is insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment required
'500':
description: Internal Server Error — something went wrong on our side.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Error
tags:
- Homestra
/v2/homestra/ad:
get:
summary: Homestra Ad
description: 'Retrieve detailed property listing data from Homestra, including price, size, location, features, photos, and nearby properties.
**Credit cost:** 1 credit per call'
operationId: get-homestra-ad
security:
- ApiKeyAuth: []
parameters:
- name: query
in: query
required: true
description: "A Homestra property URL or slug.\n\n**Examples:**\n\n https://homestra.com/property/charming-4-bedroom-stone-house-with-historic-towers-in-idyllic-french-village/\n\nBoth the full URL and the slug (the last part of the URL path) are accepted."
schema:
type: string
description: "A Homestra property URL or slug.\n\n**Examples:**\n\n https://homestra.com/property/charming-4-bedroom-stone-house-with-historic-towers-in-idyllic-french-village/\n\nBoth the full URL and the slug (the last part of the URL path) are accepted."
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/is_async'
- $ref: '#/components/parameters/soft_fail'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
id:
type: string
city:
type: string
size:
type: integer
slug:
type: string
type:
type: string
price:
type: integer
title:
type: string
garden:
type: boolean
region:
type: string
status:
type: string
address:
type: string
parking:
type: boolean
basement:
type: boolean
location:
type: object
properties:
type:
type: string
coordinates:
type: array
items:
type: number
lot_size:
type: integer
condition:
type: string
furnished:
type: boolean
created_at:
type: string
country_code:
type: string
swimming_pool:
type: boolean
nearby_properties:
type: array
items:
type: object
properties:
id:
type: string
slug:
type: string
price:
type: integer
title:
type: string
amount_of_bedrooms:
type: integer
featured_photo_url:
type: string
amount_of_bathrooms:
type: integer
examples:
Get chateau listing in Civray, France:
value:
id: c6ff90a7-d152-42c9-a1a3-ff0b5cbbcdaf
city: Civray
size: 240
slug: charming-4-bedroom-stone-house-with-historic-towers-in-idyllic-french-village
type: chateau
price: 474500
title: Charming 4-Bedroom Stone House with Historic Towers in Idyllic French Village
garden: true
region: Cher
status: for_sale
address: France
parking: true
basement: true
location:
type: Point
coordinates:
- 46.94515
- 2.17684
lot_size: 3933
condition: good
furnished: false
created_at: '2024-06-01T17:43:55.361Z'
country_code: fr
swimming_pool: false
nearby_properties:
- id: a08d69ea-888e-4ed2-8bbd-6a731efd1bd5
slug: charming-3-bedroom-home-in-aquitaine-france
price: 275000
title: Charming 3 Bedroom Home in Aquitaine, France
amount_of_bedrooms: 4
featured_photo_url: https://storage.googleapis.com/homestra-images/property-image-cab7dff4-ce7b-4f20-9d35-2df09ae9d283-1717266265.jpg
amount_of_bathrooms: 1
'400':
description: Bad Request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
'401':
description: Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidKey:
value:
error: Invalid API Key
planRateLimit:
value:
error: 'Rate limit exceeded: You''ve exceeded the per second rate limit on your subscription'
keyQuota:
value:
error: 'Rate limit exceeded for the API key: quota monthly'
'402':
description: Payment Required — your subscription or credit balance is insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment required
'500':
description: Internal Server Error — something went wrong on our side.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Error
tags:
- Homestra
post:
summary: Homestra Ad
description: 'Retrieve detailed property listing data from Homestra, including price, size, location, features, photos, and nearby properties.
**Credit cost:** 1 credit per call'
operationId: post-homestra-ad
security:
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/is_async'
- $ref: '#/components/parameters/soft_fail'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: string
description: "A Homestra property URL or slug.\n\n**Examples:**\n\n https://homestra.com/property/charming-4-bedroom-stone-house-with-historic-towers-in-idyllic-french-village/\n\nBoth the full URL and the slug (the last part of the URL path) are accepted."
required:
- query
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
id:
type: string
city:
type: string
size:
type: integer
slug:
type: string
type:
type: string
price:
type: integer
title:
type: string
garden:
type: boolean
region:
type: string
status:
type: string
address:
type: string
parking:
type: boolean
basement:
type: boolean
location:
type: object
properties:
type:
type: string
coordinates:
type: array
items:
type: number
lot_size:
type: integer
condition:
type: string
furnished:
type: boolean
created_at:
type: string
country_code:
type: string
swimming_pool:
type: boolean
nearby_properties:
type: array
items:
type: object
properties:
id:
type: string
slug:
type: string
price:
type: integer
title:
type: string
amount_of_bedrooms:
type: integer
featured_photo_url:
type: string
amount_of_bathrooms:
type: integer
examples:
Get chateau listing in Civray, France:
value:
id: c6ff90a7-d152-42c9-a1a3-ff0b5cbbcdaf
city: Civray
size: 240
slug: charming-4-bedroom-stone-house-with-historic-towers-in-idyllic-french-village
type: chateau
price: 474500
title: Charming 4-Bedroom Stone House with Historic Towers in Idyllic French Village
garden: true
region: Cher
status: for_sale
address: France
parking: true
basement: true
location:
type: Point
coordinates:
- 46.94515
- 2.17684
lot_size: 3933
condition: good
furnished: false
created_at: '2024-06-01T17:43:55.361Z'
country_code: fr
swimming_pool: false
nearby_properties:
- id: a08d69ea-888e-4ed2-8bbd-6a731efd1bd5
slug: charming-3-bedroom-home-in-aquitaine-france
price: 275000
title: Charming 3 Bedroom Home in Aquitaine, France
amount_of_bedrooms: 4
featured_photo_url: https://storage.googleapis.com/homestra-images/property-image-cab7dff4-ce7b-4f20-9d35-2df09ae9d283-1717266265.jpg
amount_of_bathrooms: 1
'400':
description: Bad Request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
'401':
description: Unauthorized — the API key is missing, invalid, inactive, or expired, or a rate limit was exceeded (`Rate limit exceeded…` message).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidKey:
value:
error: Invalid API Key
planRateLimit:
value:
error: 'Rate limit exceeded: You''ve exceeded the per second rate limit on your subscription'
keyQuota:
value:
error: 'Rate limit exceeded for the API key: quota monthly'
'402':
description: Payment Required — your subscription or credit balance is insufficient.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment required
'500':
description: Internal Server Error — something went wrong on our side.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Error
tags:
- Homestra
components:
parameters:
fields:
name: fields
in: query
required: false
description: Comma-separated list of response fields to return, with dot notation for nested fields (e.g. `name,location.city`).
schema:
type: string
is_async:
name: is_async
in: query
required: false
description: 'Run the request as a background job: the API answers `202` with a `job_id` to poll on `GET /v1/jobs/{id}`.'
schema:
type: boolean
default: false
soft_fail:
name: soft_fail
in: query
required: false
description: Return HTTP 200 even when the request fails; the error is in the `error` field of the body.
schema:
type: boolean
default: false
schemas:
ErrorResponse:
type: object
required:
- error
properties:
error:
type: string
description: Human-readable error message.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Your API key. Include it in the x-api-key header for every request.