Οδηγός ενσωμάτωσης του Housing Market API
Οι πίνακες αναφοράς, οι περιγραφές των τελικών σημείων, οι κωδικοί σφαλμάτων και τα παραδείγματα παράγονται από την προδιαγραφή του API και παραμένουν στα αγγλικά σε κάθε γλώσσα. Τα ονόματα, οι παράμετροι και οι κωδικοί είναι παντού ίδιοι.
Τελικό σημείο ακινήτων και αναφορά πεδίων
Το GET /v1/properties επιστρέφει δημοσιευμένες αγγελίες για μία χώρα, με όλες τις λεπτομέρειες ακινήτων που επιτρέπεται να βλέπει ένα κλειδί Standard.
Κάθε πεδίο ανήκει σε μία από τις παρακάτω ομάδες, η οποία εμφανίζεται στη στήλη πολιτικής.
- Δομημένο (Structured): επιστρέφεται όπως δημοσιεύτηκε.
- Γενικευμένο (Coarsened): ο αριθμός οδού δεν επιστρέφεται ποτέ, ενώ για κατοικίες που αγγέλλονται από τον ιδιοκτήτη τους οι συντεταγμένες στρογγυλοποιούνται σε επίπεδο γειτονιάς και ο ταχυδρομικός κώδικας παρακρατείται.
- Εκκαθαρισμένο (Scrubbed): ελεύθερο κείμενο από το άτομο που καταχώρισε το ακίνητο, από το οποίο έχουν αφαιρεθεί διευθύνσεις email, αριθμοί τηλεφώνου, διευθύνσεις ιστού και αναγνωριστικά εφαρμογών ανταλλαγής μηνυμάτων.
- Παράγωγο (Derived): υπολογίζεται από το API με βάση άλλα πεδία.
- Μέσω διαμεσολάβησης (Proxied): παρέχεται μέσω του API αντί να συνδέεται απευθείας.
Προς το παρόν, οι αγγελίες επιστρέφονται χωρίς εικόνες: το πεδίο images είναι μια κενή λίστα. Οι σύνδεσμοι εικόνων έρχονται· οι πρωτότυπες φωτογραφίες παραμένουν δημόσιες στις πύλες Housing Market.
Δεν επιστρέφονται ποτέ: τα στοιχεία επικοινωνίας του ατόμου που καταχώρισε το ακίνητο, η ταυτότητα μεσιτών και ιδιοκτητών και οτιδήποτε ιδιωτικό σε μια αγγελία.
Οι τιμές είναι στο νόμισμα της ίδιας της αγγελίας και δεν μετατρέπονται ποτέ. Ένα πεδίο χωρίς τιμή είναι null.
Η εγγραφή ακινήτου
GET /v1/properties: List published properties in one country
| Field | Type | Policy | Description |
|---|---|---|---|
id required | string | Structured | Stable identifier of the listing. Treat it as opaque. |
country required | string | Structured | ISO 3166-1 alpha-2 code of the country the listing is in. |
listing_type required | string | Structured | What the listing offers. Requesting listing_type=all returns every value. sale rent vacation_rental co_living |
property_type required | string | null | Structured | The kind of property in lower case, for example condominium or house. Null when the listing does not state one. |
province | string | null | Structured | Name of the province or state. |
province_id | integer | null | Structured | Identifier of the province or state, for the province_id filter. |
city | string | null | Structured | Name of the city. |
city_id | integer | null | Structured | Identifier of the city, for the city_id filter. |
area | string | null | Structured | Name of the district or area. |
area_id | integer | null | Structured | Identifier of the district or area, for the area_id filter. |
address | string | null | Coarsened | Street name or locality line. The street number is never included. |
post_code | string | null | Coarsened | Postal code. Null for owner-listed homes. |
latitude | number | null | Coarsened | Latitude in decimal degrees. For owner-listed homes it is rounded so that it identifies a neighbourhood, not a building; see location_precision. |
longitude | number | null | Coarsened | Longitude in decimal degrees. Same precision rule as latitude. |
location_precision required | string | Derived | approximate when the coordinates and post code have been coarsened because the home is listed by its owner; otherwise exact. exact approximate |
price | number | null | Structured | Published price in the listing's own currency. For rent listings it is the published amount per month. Never converted. |
price_max | number | null | Structured | Upper end when the listing publishes a price range; otherwise null. |
currency required | string | null | Structured | ISO 4217 code of the currency price and price_max are in. Null when the listing states none. |
bedrooms | number | null | Structured | Number of bedrooms. |
bathrooms | number | null | Structured | Number of bathrooms. |
rooms | number | null | Structured | Total number of rooms, where the listing states it. |
living_area | number | null | Structured | Living area in the unit the lister used. Use living_area_sqm to compare listings. |
living_area_sqm | number | null | Structured | Living area in square metres. |
lot_area | number | null | Structured | Plot area in the unit the lister used. Use lot_area_sqm to compare listings. |
lot_area_sqm | number | null | Structured | Plot area in square metres. |
build_year | integer | null | Structured | Year the property was built. |
published_date required | string | null (date-time) | Structured | When the listing was first published. Null when the portal does not record it. |
last_updated required | string | null (date-time) | Structured | When the listing last changed, or published_date when no change is recorded. This is the value updated_since compares. |
features | array of string | Structured | Feature names, for example the facilities of the building. |
appliances | array of string | Structured | Appliance names included with the property. |
neighbourhood | array of string | Structured | Names of neighbourhood features, such as nearby transport. |
tags | array of string | Structured | Tag names the lister attached to the listing. |
developer | string | null | Structured | Name of the development company, where the listing names one. Never a person. |
summary | string | null | Scrubbed | Short description. Email addresses, phone numbers, web addresses and messaging handles are removed. |
description | string | null | Scrubbed | Full description as plain text. Email addresses, phone numbers, web addresses and messaging handles are removed. |
location_text | string | null | Scrubbed | The lister's description of the location, scrubbed in the same way. |
images required | array of Image | Proxied | Watermarked, signed, expiring photographs. Never a direct storage or CDN address. Empty until the image service is available. |
images[]
| Field | Type | Description |
|---|---|---|
url required | string (uri) | Signed address of the watermarked image. Valid for your key only, until expires_at. |
expires_at required | string (date-time) | When the URL stops working. |
position required | integer | Order of the photograph on the listing. 1 is the lead photograph. |
GET /v1/properties/{id}
Get one published property
Returns one published listing by the id a listing page carried, in the same shape. The country must be the listing's own country and one your key covers. A listing that has been withdrawn, an id from another country, and an id that never existed all return not_found.
Parameters
| Parameter | Type | Required | Values | Description |
|---|---|---|---|---|
id | string | yes | The id of a listing, exactly as a listing page returned it. | |
country | string | yes | pattern ^[A-Z]{2}$ | ISO 3166-1 alpha-2 code of the country, for example TH. A country
outside your subscription is refused with country_not_entitled. |
Responses
| Status | Description | Error codes |
|---|---|---|
200 | The listing. | |
400 | The request is invalid. | invalid_parameter invalid_cursor |
401 | The key is missing, unknown or revoked. | unauthenticated |
403 | The request is refused for the key, the address or the country. | country_not_entitled ip_not_allowed key_paused |
404 | The listing does not exist, is not in that country, or has been withdrawn. | not_found |
429 | A rate limit or a quota has been reached. | rate_limited quota_exceeded |
500 | Something went wrong on our side. | internal_error |
503 | The service cannot answer right now. | service_unavailable |