weknowinc/latam-real-estate-listings

HF LatAm Real Estate Dataset (v5)

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

• —Version: v5
• —Sources:
• —OpenSearch properties — Costa Rica (CR)
• —OpenSearch pa_properties — Panamá (PA)
• —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 snakecase machine codes. No English label columns (`placekindlabelen`, etc.) to avoid Spanglish.
• —Config source: place_kind ids, Spanish labels (label_es), and per-country defaults come from app/utils/geo_config.py (same as agentico-admin).

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. Resolution order:

1. 1.Valid place_kind on the property document
2. 2.Linked complex (condo_id) lookup in the condos index
3. 3.Country default from geo_config (default_place_kind)

Costa Rica (CR)

• —Default (when listing has no explicit/linked classification): condominio_horizontal — Condominio horizontal

Panamá (PA)

• —Default (when listing has no explicit/linked classification): ph_horizontal — PH horizontal

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, allowed ids and Spanish labels checked against app/utils/geo_config.py

Generation

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

Also writes export_stats.json alongside this README.

Stats from this run

• —Version: v5
• —Run date: 2026-06-21
• —Cutoff month: 2026-01
• —Output rows: 10394
• —By country: {'Costa Rica': 8955, 'Panamá': 1439}
• —By operation: {'venta': 8465, 'alquiler': 1929}
• —By placekind: {'condominiohorizontal': 8942, 'condominiovertical': 13, 'phhorizontal': 1415, '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.