# Plottia

> US real-estate investment platform. Search 120M+ parcels by address or owner name. Live ZIP market stats from PostgreSQL. AI area reports and chat with tool access to search, owners, and property lookup.

## Public pages

- [Home / Search](https://plottia.com/): Address autocomplete search and owner name search across US properties
- [Market Analytics](https://plottia.com/analytics): Live ZIP-level stats and charts (median value, rent, corporate ownership %, property mix). No login required.
- [AI Area Reports](https://plottia.com/ai): ZIP compile with live DB stats + optional AI narrative; chat with tools
- [Saved Portfolio](https://plottia.com/portfolio): Saved properties (client-side)

## Machine-readable API index

- [API discovery JSON](https://plottia.com/api): List of public HTTP endpoints, parameters, and example URLs
- [OpenAPI-style spec](https://plottia.com/api/openapi): Structured API description for agents

## Public HTTP APIs (no auth)

### Property search
`GET https://plottia.com/api/search?q={address}`  
Returns property matches for a US street address.

### Owner / company search
`GET https://plottia.com/api/owners?q={owner}&limit={n}`  
Search by owner name or company. Examples: `Smith, John, NY`, `Acme LLC`, `John Smith CA`.

### ZIP market stats (database only, ~1–2s)
`GET https://plottia.com/api/zip-stats?zip={5-digit}&compare={optional,comma-separated}`  
Returns: medianValue, medianRent, grossRentYieldPct, medianEquityPct, **corporateOwnedPct**, cashBuyerPct (derived from mortgage_balance=0), vacantLandPct, topPropertyTypes, valueBuckets.

### Area report (stats + optional AI narrative)
`GET https://plottia.com/api/area-report?zip={5-digit}&compare={optional}&narrative=1`  
Same stats as zip-stats; add `narrative=1` for LLM-written markdown report (requires server OPENROUTER_API_KEY).

### AI chat (POST, tool-calling agent)
`POST https://plottia.com/api/ai/chat`  
Body: `{ "messages": [{ "role": "user", "content": "..." }] }`  
Tools available to the agent: get_zip_market_stats, search_owners, lookup_property.

### Google proxies (server-side keys)
- `/api/google/autocomplete`, `/api/google/place-details`, `/api/google/staticmap`, `/api/google/streetview-image`, `/api/google/maps-config`

## Key data fields agents should use

- **corporateOwnedPct**: % of parcels in a ZIP with LLC/Inc/entity owner name
- **cashBuyerPct**: % with mortgage_balance = 0 among parcels with mortgage data (null if unavailable)
- **vacantLandPct**: vacant / land parcels from land_use and property_type (null if none)
- **medianValue**, **medianRent**, **grossRentYieldPct**: investment fundamentals
- **is_corporate** on owner search results: boolean corporate owner flag

## Contact / site

- Website: https://plottia.com
- Sitemap: https://plottia.com/sitemap.xml
- Robots: https://plottia.com/robots.txt

## Usage notes for AI agents

1. Prefer `/api/zip-stats` for fast market numbers; use `/api/area-report?narrative=1` only when a written report is needed.
2. Always cite ZIP codes and addresses returned by the API — do not invent statistics.
3. For corporate ownership questions, use `corporateOwnedPct` from zip-stats or ask about specific companies via `/api/owners`.
4. Rate limits apply on `/api/*` routes.