Developer API · v1 · Production

Real estate intelligence, one API call away.

Integrate the TerraVision Intelligence Layer into your platform. TVI scoring, tax climate, urban safety, demographics and curated AI narratives — REST, JSON, authenticated, rate-limited and ready for production.

Request API Key Quickstart

// QUICKSTART

Authenticate & call

All endpoints require the X-Tvi-Api-Key header. Keys are issued per workspace · keep them server-side · rotate when needed.

# Get the TVI score for Lisbon
curl -H "X-Tvi-Api-Key: tv_live_…" \
  https://terravision.app/api/v1/tvi/pt-lisbon-centro

# Tax + Safety + Investor Climate
curl -H "X-Tvi-Api-Key: tv_live_…" \
  https://terravision.app/api/v1/intelligence/pt-lisbon-centro

# List all Portuguese markets
curl -H "X-Tvi-Api-Key: tv_live_…" \
  https://terravision.app/api/v1/markets/list?country=PT

# Your current quota usage
curl -H "X-Tvi-Api-Key: tv_live_…" \
  https://terravision.app/api/v1/usage

// ENDPOINTS

5 production endpoints

GET/tvi/{zone_id}

100 req/min

TVI score + recommendation

{
  "zone_id": "pt-lisbon-centro",
  "name": "Lisboa Centro",
  "country": "PT",
  "currency": "EUR",
  "opportunity_score": 8.4,
  "risk_score": 3.2,
  "recommendation": "INVEST",
  "tvi": 7.0,
  "as_of": "2026-05-26T08:00:00Z"
}

GET/intelligence/{zone_id}

60 req/min

Tax · Safety · Investor Climate

{
  "zone_id": "pt-lisbon-centro",
  "tax": { "yield_gross_pct": 4.8, "yield_net_estimate_pct": 3.4,
           "tax_burden_label": "Moderate", "regulatory_stability_label": "High", ... },
  "safety": { "safety_score": 7.8, "crime_trend": "improving", ... },
  "climate": { "rating_label": "Balanced", "rating_score": 7.0,
               "headline": "Structural demand meets fiscal moderation", ... },
  "tax_sources": ["OECD Tax Database 2024", "PwC PT Tax Summary 2025"],
  "as_of": "2026-05-26T08:00:00Z"
}

GET/demographics/{zone_id}

100 req/min

Official + AI-augmented demographics

{
  "zone_id": "us-miami",
  "country": "US",
  "data": { "population": 443665, "median_age": 39.7,
            "median_income_local": 54858, "provider": "census_us",
            "data_status": "official",
            "source": "US Census ACS 5y · place 1245000", ... },
  "as_of": "2026-05-26T08:00:00Z"
}

GET/markets/list?country=PT

30 req/min

List zones (optional country filter)

{
  "total": 3,
  "markets": [
    { "zone_id": "pt-lisbon-centro", "country": "PT", "city": "Lisboa",
      "tvi": { "tvi": 7.0, ... }, "opportunity_score": 8.4, "risk_score": 3.2 },
    { "zone_id": "pt-almada", ... },
    { "zone_id": "pt-porto", ... }
  ]
}

GET/usage

60 req/min

Your monthly usage + quota

{
  "plan": "starter",
  "plan_label": "Starter",
  "monthly_quota": 5000,
  "calls_this_month": 184,
  "calls_total": 1206,
  "billing_period": "2026-05",
  "price_per_call_cents": 5
}

// AUTH

Authentication & rate limits

Header-based auth

Send X-Tvi-Api-Key on every request. Keys are SHA-256 hashed at rest.

Rate limits

Per endpoint: 30–100 req/min. 429 with Retry-After when exceeded.

Monthly quota

Auto-resets on the 1st UTC. Track via /usage. Upgrade to extend.

// PRICING

API plans

Plan	Monthly quota	Price	Overage
Free	100 calls/mo	€0	—
Starter	5 000 calls/mo	€49/mo	€0.05/call
Pro	50 000 calls/mo	€199/mo	€0.04/call
Enterprise	500 000+ calls/mo	Custom	Custom

// REQUEST API KEY

Get developer access.

Tell us about your integration. We respond within 24 business hours with your API key, plan recommendation and sample integration code.

Looking for white-label or enterprise SLA? /b2b →