# Offramp City Data API

> Retirement-focused financial data for AI agents planning geographic arbitrage.

## What This API Does

Offramp provides financial data for 500+ cities worldwide, specifically curated for retirement planning:

- **Cost of Living**: Monthly expenses, cost index relative to NYC
- **Tax Rates**: Effective rates for retirement income, special programs (Portugal NHR, Panama Pensionado)
- **Healthcare Costs**: Quality index and cost multiplier vs US baseline
- **Visa Requirements**: Accessibility scores, income requirements, path to citizenship
- **Safety**: Crime indices from Numbeo
- **Climate**: Sunshine hours, average temperatures
- **Expat Community**: Population estimates, English friendliness

## The Offramp Index

Our proprietary 0-100 score measuring retirement-friendliness:
- Cost of Living (35%)
- Safety (15%)
- Healthcare Quality (15%)
- Climate (12%)
- Visa Accessibility (10%)
- Expat Community (8%)
- Air Quality (5%)

Higher score = better for retirement.

## Quick Start

**Supabase Anon Key** (public, use in all requests):
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InpzcmlpZG9mb2JrbXp0cWFiZnN0Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjAwMjAzOTQsImV4cCI6MjA3NTU5NjM5NH0.BTR8LN053UH4-qBNHSgZ6uomXT3LEOUyfGra4QfTMwI
```

```bash
# 1. Get a free API key (100 calls included)
curl -X POST https://zsriidofobkmztqabfst.supabase.co/functions/v1/agent-api/auth/register \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InpzcmlpZG9mb2JrbXp0cWFiZnN0Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjAwMjAzOTQsImV4cCI6MjA3NTU5NjM5NH0.BTR8LN053UH4-qBNHSgZ6uomXT3LEOUyfGra4QfTMwI" \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com"}'

# 2. Query a city (replace sk_live_YOUR_KEY with key from step 1)
curl "https://zsriidofobkmztqabfst.supabase.co/functions/v1/agent-api/v1/city?name=lisbon" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InpzcmlpZG9mb2JrbXp0cWFiZnN0Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjAwMjAzOTQsImV4cCI6MjA3NTU5NjM5NH0.BTR8LN053UH4-qBNHSgZ6uomXT3LEOUyfGra4QfTMwI" \
  -H "x-api-key: sk_live_YOUR_KEY"
```

## Endpoints

| Endpoint | Method | Cost | Description |
|----------|--------|------|-------------|
| `/v1/city?name=X` | GET | $0.008 | Full city profile |
| `/v1/city/col?name=X` | GET | $0.002 | Cost of living only |
| `/v1/city/tax?name=X` | GET | $0.002 | Tax rate only |
| `/v1/city/healthcare?name=X` | GET | $0.002 | Healthcare only |
| `/v1/cities` | GET | $0.005 | List all cities |
| `/v1/cities/ranked` | GET | $0.005 | Cities by Offramp Index |
| `/auth/register` | POST | Free | Create API key |
| `/auth/balance` | GET | Free | Check balance |
| `/billing/checkout` | POST | Free | Top up balance |

## Authentication

All data endpoints require:
1. Supabase anon key in `Authorization: Bearer <key>` header
2. Your API key in `x-api-key` header

## Pricing

- New keys start with $0.80 balance (100 free calls)
- Minimum top-up: $5
- Per-call pricing: $0.002 - $0.008

## Data Quality Tiers

- `verified`: All data from reliable sources (Numbeo, government)
- `partial`: Tax and healthcare verified, other fields estimated
- `unverified`: AI estimates, use with caution

## Example Response

```json
{
  "success": true,
  "data": {
    "city": "Lisbon",
    "country": "Portugal",
    "offramp_index": 65,
    "cost_of_living": {
      "index": 54.09,
      "multiplier": 0.6,
      "avg_monthly_usd": 2400,
      "source": "numbeo",
      "date": "2026-01-01"
    },
    "tax": {
      "effective_rate": 0,
      "notes": "NHR program: 0% on foreign income for 10 years",
      "source": "manual_2026"
    }
  },
  "meta": {
    "data_quality": "verified",
    "balance_remaining": 0.792,
    "cost": 0.008
  }
}
```

## Top Cities by Offramp Index

1. Chiang Mai, Thailand (68) - Ultra-low cost, excellent healthcare
2. Lisbon, Portugal (65) - NHR tax program, EU access
3. Mexico City, Mexico (63) - Close to US, affordable healthcare
4. Medellín, Colombia (61) - Spring climate, growing expat scene
5. Bangkok, Thailand (60) - World-class healthcare, low cost

## Use Cases for AI Agents

1. **Retirement Planning**: "Where can I retire on $2,000/month?"
2. **Tax Optimization**: "Which countries have 0% tax on foreign income?"
3. **Healthcare Comparison**: "Where is quality healthcare most affordable?"
4. **Visa Research**: "Which countries offer easy retirement visas?"
5. **City Comparison**: "Compare Lisbon vs Porto for retirement"

## OpenAPI Spec

Full specification: https://offramp.live/openapi.yaml

## Support

- Website: https://offramp.live
- API Status: Check `/auth/balance` endpoint