{"openapi":"3.0.3","info":{"title":"Nexus Real Estates Public API","description":"Public API for accessing property listings from Nexus Real Estates website. All endpoints require API key authentication.","version":"1.0.0","contact":{"name":"API Support","email":"support@nexusrealestates.com"}},"servers":[{"url":"https://www.nexusrealestates.com/api/public","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/properties":{"get":{"summary":"Get properties list","description":"Retrieve a paginated list of active properties with optional filtering","operationId":"getProperties","tags":["Properties"],"parameters":[{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","description":"Items per page (maximum 50)","schema":{"type":"integer","default":20,"minimum":1,"maximum":50}},{"name":"sort","in":"query","description":"Sort field (prefix with - for descending, e.g., -created)","schema":{"type":"string","example":"-created"}},{"name":"ref","in":"query","description":"Filter by property reference number","schema":{"type":"string"}},{"name":"property_type","in":"query","description":"Filter by property type (e.g., apartment, villa, house)","schema":{"type":"string"}},{"name":"sale_rent","in":"query","description":"Filter by sale or rent","schema":{"type":"string","enum":["for_sale","for_rent"]}},{"name":"location","in":"query","description":"Filter by location ID","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by property status","schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Minimum price","schema":{"type":"number"}},{"name":"max_price","in":"query","description":"Maximum price","schema":{"type":"number"}},{"name":"min_internal_area","in":"query","description":"Minimum internal area in square meters","schema":{"type":"number"}},{"name":"max_internal_area","in":"query","description":"Maximum internal area in square meters","schema":{"type":"number"}},{"name":"min_plot_area","in":"query","description":"Minimum plot area in square meters","schema":{"type":"number"}},{"name":"max_plot_area","in":"query","description":"Maximum plot area in square meters","schema":{"type":"number"}},{"name":"min_bedrooms","in":"query","description":"Minimum number of bedrooms","schema":{"type":"integer"}},{"name":"max_bedrooms","in":"query","description":"Maximum number of bedrooms","schema":{"type":"integer"}},{"name":"min_bathrooms","in":"query","description":"Minimum number of bathrooms","schema":{"type":"integer"}},{"name":"max_bathrooms","in":"query","description":"Maximum number of bathrooms","schema":{"type":"integer"}},{"name":"min_floor","in":"query","description":"Minimum floor number","schema":{"type":"integer"}},{"name":"max_floor","in":"query","description":"Maximum floor number","schema":{"type":"integer"}},{"name":"construction_stage","in":"query","description":"Construction stage (comma-separated for multiple, e.g., completed,under_construction)","schema":{"type":"string"}},{"name":"min_construction_year","in":"query","description":"Minimum construction year","schema":{"type":"integer"}},{"name":"max_construction_year","in":"query","description":"Maximum construction year","schema":{"type":"integer"}},{"name":"elevator","in":"query","description":"Has elevator","schema":{"type":"boolean"}},{"name":"private_pool","in":"query","description":"Has private swimming pool","schema":{"type":"boolean"}},{"name":"common_pool","in":"query","description":"Has common swimming pool","schema":{"type":"boolean"}},{"name":"sea_view","in":"query","description":"Has sea view","schema":{"type":"boolean"}},{"name":"beach_front","in":"query","description":"Beach front property","schema":{"type":"boolean"}},{"name":"alarm","in":"query","description":"Has alarm system","schema":{"type":"boolean"}},{"name":"air_condition","in":"query","description":"Has air conditioning","schema":{"type":"boolean"}},{"name":"covered_parking","in":"query","description":"Has covered parking","schema":{"type":"boolean"}},{"name":"uncovered_parking","in":"query","description":"Has uncovered parking","schema":{"type":"boolean"}},{"name":"garden","in":"query","description":"Has garden","schema":{"type":"boolean"}},{"name":"renovated","in":"query","description":"Recently renovated","schema":{"type":"boolean"}},{"name":"golden_visa","in":"query","description":"Golden visa eligible","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Property"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/properties/{id}":{"get":{"summary":"Get single property","description":"Retrieve detailed information about a specific property","operationId":"getProperty","tags":["Properties"],"parameters":[{"name":"id","in":"path","required":true,"description":"Property ID (UUID)","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Property"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Property not found or not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication. Contact support to obtain your API key."}},"schemas":{"Property":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique property identifier"},"ref":{"type":"integer","description":"Property reference number"},"name":{"type":"string","description":"Property name"},"description":{"type":"string","description":"Full property description"},"property_type":{"type":"string","description":"Property type"},"status":{"type":"string","description":"Property status"},"bedrooms":{"type":"integer","description":"Number of bedrooms"},"bathrooms":{"type":"integer","description":"Number of bathrooms"},"kitchens":{"type":"integer","description":"Number of kitchens"},"living_rooms":{"type":"integer","description":"Number of living rooms"},"floor_number":{"type":"integer","description":"Floor number"},"internal_area_amount":{"type":"string","description":"Internal area in square meters"},"covered_area_amount":{"type":"string","description":"Covered area in square meters"},"covered_verandas_amount":{"type":"string","description":"Covered verandas area"},"uncovered_area_amount":{"type":"string","description":"Uncovered area"},"uncovered_verandas_amount":{"type":"string","description":"Uncovered verandas area"},"storage_amount":{"type":"string","description":"Storage area"},"plot_area_amount":{"type":"string","description":"Plot area"},"total_area_amount":{"type":"string","description":"Total area"},"garden_area_amount":{"type":"string","description":"Garden area"},"list_selling_price_amount":{"type":"string","description":"Listing price"},"price_qualifier":{"type":"string","description":"Price qualifier (e.g., POA)"},"country":{"type":"string","description":"Country"},"city":{"type":"string","description":"City"},"district":{"type":"string","description":"District"},"area":{"type":"string","description":"Area/neighborhood"},"listing_date":{"type":"string","format":"date","description":"Listing date"},"furnished":{"type":"boolean","description":"Whether property is furnished"},"construction_type":{"type":"string","description":"Construction type"},"construction_year":{"type":"integer","description":"Year of construction"},"renovation_year":{"type":"integer","description":"Year of renovation"},"covered_parking":{"type":"integer","description":"Covered parking spaces"},"uncovered_parking":{"type":"integer","description":"Uncovered parking spaces"},"elevator":{"type":"boolean","description":"Has elevator"},"storage_space":{"type":"boolean","description":"Has storage space"},"fireplace":{"type":"boolean","description":"Has fireplace"},"air_condition":{"type":"string","description":"Air conditioning type"},"heating_type":{"type":"string","description":"Heating type"},"heating_medium":{"type":"string","description":"Heating medium (e.g., electricity, gas)"},"cooling_type":{"type":"string","description":"Cooling/air conditioning type"},"alarm":{"type":"boolean","description":"Has alarm system"},"secure_door":{"type":"boolean","description":"Has secure door"},"sea_view":{"type":"boolean","description":"Has sea view"},"mountain_view":{"type":"boolean","description":"Has mountain view"},"energy_efficiency_grade":{"type":"string","description":"Energy efficiency grade"},"media":{"type":"array","description":"Property media files","items":{"$ref":"#/components/schemas/Media"}},"custom_golden_visa_eligible":{"type":"boolean","nullable":true,"description":"Golden visa eligibility"}}},"Media":{"type":"object","properties":{"id":{"type":"string","description":"Media ID"},"media_type":{"type":"string","description":"Media type (image, video, etc.)"},"display_order":{"type":"integer","description":"Display order"},"file":{"type":"object","properties":{"href":{"type":"string","format":"uri","description":"Full size image URL"},"thumbnails":{"type":"object","properties":{"huge":{"type":"string","format":"uri"},"xlarge":{"type":"string","format":"uri"},"large":{"type":"string","format":"uri"},"medium":{"type":"string","format":"uri"},"small":{"type":"string","format":"uri"},"tiny":{"type":"string","format":"uri"}}}}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Items per page"},"total":{"type":"integer","description":"Total number of items"},"pages":{"type":"integer","description":"Total number of pages"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}},"responses":{"UnauthorizedError":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Unauthorized - Invalid API key"}}}},"RateLimitError":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit resets","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"resetTime":{"type":"string","format":"date-time"}}},"example":{"error":"Rate limit exceeded. Please try again later.","resetTime":"2024-01-20T15:30:00Z"}}}},"ServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"An error occurred while fetching properties"}}}}}},"tags":[{"name":"Properties","description":"Property listing endpoints"}]}