{"openapi":"3.1.0","info":{"title":"Aborio Public Listings API","version":"1.0.0","description":"Read-only public listing search API for AI agents and integrations."},"servers":[{"url":"https://staging.aborio.es"}],"paths":{"/api/listings/search":{"get":{"summary":"Search public Aborio listings","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string"}},{"name":"province","in":"query","required":false,"schema":{"type":"string"}},{"name":"listing_reference","in":"query","required":false,"schema":{"type":"string"}},{"name":"listing_type","in":"query","required":false,"schema":{"type":"string","enum":["rent","sale"]}},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","enum":["apartment","house","room","studio"]}},{"name":"min_price_cents","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_price_cents","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_bedrooms","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_bedrooms","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_bathrooms","in":"query","required":false,"schema":{"type":"number"}},{"name":"max_bathrooms","in":"query","required":false,"schema":{"type":"number"}},{"name":"min_area_sqm","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_area_sqm","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_floor","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_floor","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_photos_count","in":"query","required":false,"schema":{"type":"integer"}},{"name":"furnished","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"ground_floor","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"middle_floor","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"high_floor","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"pets_allowed","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"sale_electricity_off","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"sale_water_off","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"sale_viewing_unavailable","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"min_energy_rating","in":"query","required":false,"schema":{"type":"string"}},{"name":"latitude","in":"query","required":false,"schema":{"type":"number"}},{"name":"longitude","in":"query","required":false,"schema":{"type":"number"}},{"name":"radius_km","in":"query","required":false,"schema":{"type":"number"}},{"name":"max_distance_to_sea_meters","in":"query","required":false,"schema":{"type":"integer"}},{"name":"published_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"published_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"available_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"available_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_in_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_in_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_out_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_out_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"stay_duration_value","in":"query","required":false,"schema":{"type":"integer"}},{"name":"stay_duration_unit","in":"query","required":false,"schema":{"type":"string","enum":["days","weeks","months","years"]}},{"name":"price_billing_period","in":"query","required":false,"schema":{"type":"string","enum":["daily","monthly"]}},{"name":"amenity_slugs","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated amenity slugs."}},{"name":"sale_legal_statuses","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated sale legal statuses.","example":"fully_legal,bank_owned"}},{"name":"area_polygon","in":"query","required":false,"schema":{"type":"string","description":"Semicolon-separated latitude,longitude polygon points; maximum encoded length 10,000."}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["recommended","price_asc","price_desc","largest"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Public listing search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicListingCollection"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/listings/{id}":{"get":{"summary":"Fetch one public Aborio listing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Public listing detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicListingEnvelope"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/listings/{id}/contact-options":{"get":{"summary":"Fetch public contact/application options for one listing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Public listing contact options","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/listings/recent":{"get":{"summary":"Fetch newest public Aborio listings","parameters":[{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Recent public listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicListingArrayEnvelope"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/listings/updated-since":{"get":{"summary":"Fetch public listings updated since an ISO 8601 timestamp","parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Updated public listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicListingArrayEnvelope"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/listings/search-metadata":{"get":{"summary":"Fetch supported filters and location metadata","responses":{"200":{"description":"Public listing search metadata","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/locations":{"get":{"summary":"Fetch public listing locations with counts","responses":{"200":{"description":"Public listing locations","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/locations/{slug}/listings":{"get":{"summary":"Fetch public listings for one location slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"listing_type","in":"query","required":false,"schema":{"type":"string","enum":["rent","sale"]}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Public listings for a location","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Public resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/market-insights":{"get":{"summary":"Fetch aggregate market insight summaries for matching public listings","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string"}},{"name":"province","in":"query","required":false,"schema":{"type":"string"}},{"name":"listing_reference","in":"query","required":false,"schema":{"type":"string"}},{"name":"listing_type","in":"query","required":false,"schema":{"type":"string","enum":["rent","sale"]}},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","enum":["apartment","house","room","studio"]}},{"name":"min_price_cents","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_price_cents","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_bedrooms","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_bedrooms","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_bathrooms","in":"query","required":false,"schema":{"type":"number"}},{"name":"max_bathrooms","in":"query","required":false,"schema":{"type":"number"}},{"name":"min_area_sqm","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_area_sqm","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_floor","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_floor","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_photos_count","in":"query","required":false,"schema":{"type":"integer"}},{"name":"furnished","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"ground_floor","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"middle_floor","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"high_floor","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"pets_allowed","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"sale_electricity_off","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"sale_water_off","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"sale_viewing_unavailable","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"min_energy_rating","in":"query","required":false,"schema":{"type":"string"}},{"name":"latitude","in":"query","required":false,"schema":{"type":"number"}},{"name":"longitude","in":"query","required":false,"schema":{"type":"number"}},{"name":"radius_km","in":"query","required":false,"schema":{"type":"number"}},{"name":"max_distance_to_sea_meters","in":"query","required":false,"schema":{"type":"integer"}},{"name":"published_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"published_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"available_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"available_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_in_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_in_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_out_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_out_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"stay_duration_value","in":"query","required":false,"schema":{"type":"integer"}},{"name":"stay_duration_unit","in":"query","required":false,"schema":{"type":"string","enum":["days","weeks","months","years"]}},{"name":"price_billing_period","in":"query","required":false,"schema":{"type":"string","enum":["daily","monthly"]}},{"name":"amenity_slugs","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated amenity slugs."}},{"name":"sale_legal_statuses","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated sale legal statuses.","example":"fully_legal,bank_owned"}},{"name":"area_polygon","in":"query","required":false,"schema":{"type":"string","description":"Semicolon-separated latitude,longitude polygon points; maximum encoded length 10,000."}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["recommended","price_asc","price_desc","largest"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Public market insights","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search.schema.json":{"get":{"summary":"Fetch Schema.org ItemList data for a filtered listing search","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string"}},{"name":"province","in":"query","required":false,"schema":{"type":"string"}},{"name":"listing_reference","in":"query","required":false,"schema":{"type":"string"}},{"name":"listing_type","in":"query","required":false,"schema":{"type":"string","enum":["rent","sale"]}},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","enum":["apartment","house","room","studio"]}},{"name":"min_price_cents","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_price_cents","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_bedrooms","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_bedrooms","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_bathrooms","in":"query","required":false,"schema":{"type":"number"}},{"name":"max_bathrooms","in":"query","required":false,"schema":{"type":"number"}},{"name":"min_area_sqm","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_area_sqm","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_floor","in":"query","required":false,"schema":{"type":"integer"}},{"name":"max_floor","in":"query","required":false,"schema":{"type":"integer"}},{"name":"min_photos_count","in":"query","required":false,"schema":{"type":"integer"}},{"name":"furnished","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"ground_floor","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"middle_floor","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"high_floor","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"pets_allowed","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"sale_electricity_off","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"sale_water_off","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"sale_viewing_unavailable","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"min_energy_rating","in":"query","required":false,"schema":{"type":"string"}},{"name":"latitude","in":"query","required":false,"schema":{"type":"number"}},{"name":"longitude","in":"query","required":false,"schema":{"type":"number"}},{"name":"radius_km","in":"query","required":false,"schema":{"type":"number"}},{"name":"max_distance_to_sea_meters","in":"query","required":false,"schema":{"type":"integer"}},{"name":"published_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"published_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"available_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"available_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_in_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_in_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_out_from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"move_out_to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"stay_duration_value","in":"query","required":false,"schema":{"type":"integer"}},{"name":"stay_duration_unit","in":"query","required":false,"schema":{"type":"string","enum":["days","weeks","months","years"]}},{"name":"price_billing_period","in":"query","required":false,"schema":{"type":"string","enum":["daily","monthly"]}},{"name":"amenity_slugs","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated amenity slugs."}},{"name":"sale_legal_statuses","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated sale legal statuses.","example":"fully_legal,bank_owned"}},{"name":"area_polygon","in":"query","required":false,"schema":{"type":"string","description":"Semicolon-separated latitude,longitude polygon points; maximum encoded length 10,000."}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["recommended","price_asc","price_desc","largest"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Schema.org ItemList","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until a retry is recommended, when supplied by the serving layer.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"PublicListing":{"type":"object","required":["id","slug","url","title","description","listing_type","status","updated_at","pricing","property","address","amenities","photos","availability_windows","application_url","schema"],"properties":{"id":{"type":"integer"},"slug":{"type":"string"},"reference":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"listing_type":{"type":"string","enum":["rent","sale"]},"status":{"type":"string","const":"published"},"published_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"pricing":{"type":"object"},"property":{"type":"object"},"address":{"type":"object"},"geo":{"type":["object","null"]},"amenities":{"type":"array","items":{"type":"object"}},"photos":{"type":"array","items":{"type":"object"}},"availability_windows":{"type":"array","items":{"type":"object"}},"sale_conditions":{"type":["object","null"]},"application_url":{"type":"string","format":"uri"},"schema":{"type":"object"}}},"PublicListingEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicListing"}}},"PublicListingArrayEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicListing"}}}},"PublicListingCollection":{"type":"object","required":["data","page_info","suggestions","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicListing"}},"page_info":{"type":"object","required":["page","per_page","total_count","total_pages","has_next_page","has_previous_page"],"properties":{"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total_count":{"type":"integer","minimum":0},"total_pages":{"type":"integer","minimum":0},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"}}},"links":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"suggestions":{"type":"array","items":{"type":"object"}}}}}}}