latam-real-estate-listings

HF LatAm Real Estate Dataset (v4)

Export of listed real-estate properties from Costa Rica and Panama for Hugging Face consumption (NLP, modeling, search, recommendation, price prediction, etc.).

• Sources: OpenSearch properties (CR) and pa_properties (PA) indices
• Filters: status=listed, listing_date <= cutoff (default ~5 months old), must have price + (built or fallback) area
• Rows: one row per (property, operation) side. sale_and_rental expands to two rows with :venta/:alquiler suffixes in record_id.
• record_id format: {CR|PA}:{firestore_id}:{venta|alquiler}
• Language: Spanish-first — descriptions, labels, operation types, and property types are in Spanish. place_kind uses language-neutral snake_case machine codes. No English label columns (place_kind_label_en, etc.) to avoid Spanglish.

Place classification (place_kind)

Each row includes a standardized place type describing the kind of development or building context (e.g. vertical condominium, horizontal PH, office center, commercial plaza). This replaces legacy generic labels and is the primary field for grouping or featurizing listings by development type.

Exported fields:

Every row has a non-null place_kind valid for its country (CR or PA). When a listing has no explicit classification, the country default is applied (condominio_horizontal for CR, ph_horizontal for PA).

CR allowed values: condominio_horizontal, condominio_vertical, condominio_mixto, oficentro, parque_empresarial, zona_franca, plaza_comercial, ofibodega

PA allowed values: ph_vertical, ph_horizontal, ph_mixto, ph_comercial, edificio_de_oficinas, parque_corporativo, zona_libre, plaza_comercial

All columns

• record_id
• country
• admin_level_1, admin_level_2, admin_level_3
• place_kind, place_kind_label_es, place_kind_categoria
• human_verified
• property_type, property_subtype
• operation_type (venta | alquiler)
• price, currency, price_usd, price_per_m2_usd
• built_area_m2, lot_area_m2
• bedrooms, bathrooms, parking_spaces, construction_year
• condition
• amenities, features (arrays, may be empty)
• description_md
• listing_month

Other column notes

• admin_level_*: geographic admin names (province / canton or district / district or corregimiento).
• property_type / property_subtype: canonical Spanish housing types (e.g. apartamento, casa).
• human_verified: True when the listing was touched in backoffice (admin_updated on source).

Validation at export time

• Exact column set and order (HF_COLUMNS)
• No duplicate record_id
• Valid operation_type and country
• Every row: non-null place_kind + place_kind_label_es, validated per country via app/utils/geo_config.py

Generation

python scripts/export_hf_latam_dataset.py --dry-run --limit 200
python scripts/export_hf_latam_dataset.py --output-dir output/hf_latam_v4
python scripts/export_hf_latam_dataset.py --output-dir output/hf_latam_v4 --jsonl
python scripts/check_hf_latam_export.py --parquet output/hf_latam_v4/train.parquet

Also writes export_stats.json alongside this README.

Stats from this run

• Run date: 2026-06-19
• Cutoff month: 2026-01
• Output rows: 10420
• By country: {'Costa Rica': 8979, 'Panama': 1441}
• By operation: {'venta': 8486, 'alquiler': 1934}
• By place_kind: {'condominio_horizontal': 7716, 'condominio_vertical': 1261, 'oficentro': 2, 'ph_horizontal': 1417, 'ph_vertical': 24}

See export_stats.json for skips, null rates, and sample record IDs.

License / usage

Intended for research and model training. Verify license of original listings before redistribution.