API Documentation

Integrate property data extraction into your tools using the JSON API.

Authentication

If a PWS_API_KEY is configured on the server, all API requests must include it via one of:

Header: X-Api-Key: your-key
Query parameter: ?api_key=your-key

CORS

All API responses include CORS headers for browser-based consumers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Api-Key

All endpoints also support OPTIONS preflight requests, returning 204 No Content with the CORS headers above.

GET /public_api/v1/listings?url=...

Look up a property by URL. Returns existing data if previously extracted.

Parameters

Name	Type	Description
`url`	string	Property listing URL (required)

Example

curl "http://localhost:4321/public_api/v1/listings?url=https://www.idealista.com/inmueble/12345678/"

POST /public_api/v1/listings

Extract property data from a URL with optional HTML body. Use this when the site requires JavaScript rendering.

Body (JSON)

Name	Type	Description
`url`	string	Property listing URL (required)
`html`	string	Pre-rendered HTML (optional, max 10MB)

When HTML is provided and extraction succeeds, the response includes an extraction metadata object with fields_extracted, fields_available, and scraper_used.

Example

curl -X POST http://localhost:4321/public_api/v1/listings \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.idealista.com/inmueble/12345678/", "html": "<html>...</html>"}'

GET /public_api/v1/listings/:id

Retrieve a single listing by its ID.

Example

curl "http://localhost:4321/public_api/v1/listings/abc123"

GET /public_api/v1/supported_sites

Returns the list of supported property websites and their scraper names. Requires authentication.

Example Response

{
  "success": true,
  "sites": [
    { "host": "www.idealista.com", "scraper": "idealista" },
    { "host": "www.rightmove.co.uk", "scraper": "rightmove" }
  ]
}

GET /public_api/v1/health

Health check endpoint. No authentication required. Returns server status and loaded scraper count.

Example Response

{
  "success": true,
  "status": "ok",
  "scrapers_loaded": 16,
  "storage": "in_memory"
}

Error Codes

When an error occurs, the response includes a structured error object: { "success": false, "error": { "code": "...", "message": "..." } }

Code	HTTP Status	Description
`MISSING_URL`	400	No URL was provided in the request
`INVALID_URL`	400	The URL is not a valid HTTP/HTTPS address
`UNSUPPORTED_HOST`	400	The website is not currently supported
`MISSING_SCRAPER`	500	Server-side scraper configuration is missing
`UNAUTHORIZED`	401	Missing or invalid API key
`LISTING_NOT_FOUND`	404	No listing exists with the given ID
`RATE_LIMITED`	429	Too many requests — includes `Retry-After` header
`PAYLOAD_TOO_LARGE`	413	HTML body exceeds 10MB size limit
`UNSUPPORTED_CONTENT_TYPE`	415	POST Content-Type must be application/json or multipart/form-data

Example Error Response

{
  "success": false,
  "error": {
    "code": "MISSING_URL",
    "message": "Please provide a url"
  }
}

Response Format

All endpoints return JSON with a success boolean. On success, listing data includes:

title price_string price_float description count_bedrooms count_bathrooms constructed_area address_string latitude / longitude image_urls features for_sale / for_rent