# Area Guide — Property Investment Spain

> Interactive area guide and property search for the Spanish coast (Costa Blanca and Costa Cálida). Every area is mapped and scored with data — lifestyle, amenities, prices, community profile — to match buyers to the right place before they choose a property.

This is the data application behind https://www.propertyinvestmentspain.com. For the company knowledge catalog (who we are, services, fees, purchase-cost rates, FAQ), start at https://www.propertyinvestmentspain.com/api/knowledge.

## API Endpoints

All endpoints return JSON, are publicly readable without authentication, and send CORS headers.
Base URL: https://area-guide.propertyinvestmentspain.com

### Area matching — the "Best for You" engine as an API

- GET or POST /api/area-match
  Rank coastal areas and urbanisations by how well they match a buyer profile — budget, beach, golf, restaurants, atmosphere, rental potential, airport access. Same scoring engine and data as the interactive map. Call GET /api/area-match with no parameters for full self-documentation (parameters, allowed values, examples).
  Example: /api/area-match?budget_eur=350000&beach_distance=must&atmosphere=moderate_year_round&airport=very_important
  Returns: ranked areas (score 0-100, match level) each with top urbanisations including a natural-language explanation, price category, €/m², coordinates, canonical page URL, and a ready-made nearby-properties API link.

### Budget search — "what do I get for my budget?"

- GET or POST /api/budget-search
  Aggregate view of live listings for a budget and requirements: how many exist, median price/size/€ per m², breakdown by property type, which towns have the most supply and the best value, representative example listings, and — when requirements are too strict — what relaxing each constraint would yield. Call with no parameters for full self-documentation.
  Example: /api/budget-search?budget_eur=350000&bedrooms_min=2&lat_lng_radius_km=38.28,-0.56,45
  Returns: { query, summary, by_type, towns_with_most_supply, best_value_towns, sample_properties, if_too_few_results_relax?, metadata (data_updated), next_steps }

### Properties

- GET /api/properties
  Property listings for sale, with filtering and sorting server-side.
  Query parameters: limit (default 50), offset, priceMin, priceMax, bedroomsMin, bathroomsMin, sizeMin, type (Villa|Apartment|House|Plot), town, newBuild (true|false), hasPool (true|false), views, lat + lng (sort by distance), sortBy (distance|price), ids (comma-separated), view=list (compact list shape)
  Returns: { properties: [...], total, limit, offset, hasMore, dataUpdated, filters } — property objects have id, title, type, town, province, price, bedrooms, bathrooms, size_m2, plot_m2, new_build, featured, views, images, lat, lng, listed_at. dataUpdated is the ISO timestamp of the last property-feed sync (also sent as a Last-Modified header).

- GET /api/properties/{id}
  Single property by ID.

- GET /api/properties/featured
  Featured property listings.

### Areas & Urbanisations

- GET /api/areas
  All coastal areas covered, with id, name, region and urbanisation count.

- GET /api/areas/{areaId}/urbanisations
  Urbanisations within one area.

- GET /api/urbanisations/all
  Every urbanisation across all areas, with full data (location, scores, description).
  Query parameters: area (filter by areaId)

- GET /api/urbanisations/{areaId}/{urbanisationId}
  Full detail for one urbanisation.

### Other

- GET /api/exchange-rates
  Current EUR exchange rates (via Frankfurter).

## Website Structure

- / — Interactive map of all areas
- /{region} — Region overview (e.g. /costa-blanca-north)
- /{region}/{areaId} — Area detail with score KPIs
- /properties — Property listings with search and map

## Related Resources

- Main site llms.txt: https://www.propertyinvestmentspain.com/llms.txt
- Full page index: https://www.propertyinvestmentspain.com/llms-full.txt
- OpenAPI spec (main site APIs): https://www.propertyinvestmentspain.com/openapi.json
- Sitemap: https://area-guide.propertyinvestmentspain.com/sitemap.xml