Location and LocalAreas

Draft — source-reviewed on 22 October 2026. No live municipality registry or deployment contents were queried.

Distinct location concepts

Concept	Public behavior
`city`	Optional property string representing the municipality/city; accepted as an exact search filter.
`ubicacion` / LocalArea	Optional public object `{key,label,city}`; search accepts an array of stable area keys, not database UUIDs or labels.
Free-text `area`	Optional exact text filter inside `filters`; not a public property response field.
`complex_name`	Optional exact text filter; not a public response field.
Top-level search `area`	Required geometry (`BOUNDS` or `POLYGON`), distinct from `filters.area`.
`location`	Permitted public map point and precision, not raw private coordinates.
`address_line`	Optional detail-only street/house-number line allowed by full visibility.

Do not merge these into one location field or infer one from another. Display a LocalArea's label, retain its key for selection and use its city as the parent association.

Loading municipality and LocalArea selectors

GET /api/v1/public/property-reference?destination=TENERIFE&city=... includes active local_areas for the requested city, capped at 500 and sorted by normalized city, label and key. Unknown or blank city yields an empty array. Without city, local_areas is omitted; the public endpoint does not enumerate the whole registry or expose a standalone municipality list.

Reference city matching trims whitespace, folds case, removes accents and collapses internal whitespace; reviewed aliases also match. These rules do not apply to search filters.city, which is an exact comparison. Use an agreed canonical municipality value for search; an alias accepted by the reference endpoint may produce no exact city search matches.

The website's top-level municipality selector therefore needs a separately agreed public configuration or future reviewed endpoint. Do not load authenticated CRM reference routes to fill this gap. Clear LocalArea selections when the chosen municipality changes and fetch its choices again. Cancel or ignore stale option responses.

Existing property responses can retain an assigned LocalArea even if that registry entry later becomes inactive; the choice endpoint lists active options. Render supplied labels safely and avoid silently replacing historical assignments with guessed areas.

Public location facts

location_facts, when populated, may include:

Field	Meaning
`altitude_m`	Numeric altitude in metres.
`climate_zone`	Controlled climate code; use reference labels/colors.
`distance_to_sea_m`	Numeric distance in metres.
`distance_to_airport_km`	Numeric distance in kilometres.
`distance_to_nearest_school_km`	Numeric distance in kilometres.
`distance_to_nearest_healthcare_km`	Numeric distance in kilometres.
`short_term_rental_possible`	Nullable boolean contextual fact; not a reservation feed or legal guarantee.

Unknown facts are normally omitted. Preserve false and 0 as known values. Do not calculate these from hidden coordinates or market them as live routing distances.

Climate codes are NORTHERN_TENERIFE, NORTH_EAST_SANTA_CRUZ, EASTERN_COAST, TENERIFE_SOUTH, HIGH_MOUNTAINS and LA_LAGUNA_LA_OROTAVA. The reference supplies their localized labels and colors; the public DTO does not include private investment calculations.

Visibility rules

FULL permits an exact public point and a populated address line on detail. STREET publishes the centre of a fixed 500-metre map grid cell with precision: "APPROXIMATE"; it does not publish the exact address line. HIDDEN publishes neither point nor address line. Missing, invalid or stale/unrecognized point policy also prevents a point from being returned.

The visibility enum itself is not a public response field. Render according to the returned point's precision and address availability. A hidden property can still have eligible detail and public contextual facts while being absent from map search. Read Search and map privacy.

Related operations

GET /api/v1/public/property-reference, POST /api/v1/public/properties/search and GET /api/v1/public/properties/{public_id}.