UK Property Data API — Production Version
What This Is
A paid API that lets AI agents (and humans) look up UK property data:
| Endpoint | What It Does | Data Source |
|---|---|---|
/sold-prices | Recent sale prices for a postcode | HM Land Registry (free, public) |
/yield-estimate | Estimated rental yield for a postcode | VOA council tax / rental data |
/stamp-duty | UK Stamp Duty (SDLT) calculation | HMRC rules coded in Python |
Payments are handled by the x402 protocol — an HTTP-native payment standard where AI agents pay per-request using crypto wallets.
How the Code Is Organised
uk-property-api/
│
├── app/ # All application code lives here
│ ├── main.py # The "front door" — starts the server
│ ├── config.py # All settings (read from environment variables)
│ │
│ ├── routes/ # One file per endpoint (URL path)
│ │ ├── sold_prices.py # /sold-prices
│ │ ├── yield_estimate.py # /yield-estimate
│ │ └── stamp_duty.py # /stamp-duty
│ │
│ ├── services/ # Business logic (the "brains")
│ │ ├── land_registry.py # Talks to Land Registry SPARQL API
│ │ ├── voa_rental.py # Rental yield calculations
│ │ └── sdlt.py # Stamp duty maths
│ │
│ ├── middleware/ # Code that runs BEFORE your endpoints
│ │ ├── payment.py # x402 payment verification
│ │ ├── rate_limiter.py # Stops one wallet spamming requests
│ │ └── cache.py # Redis caching (saves repeat lookups)
│ │
│ └── models/ # Data shapes (what requests/responses look like)
│ └── schemas.py # Pydantic validation models
│
├── tests/ # Automated tests
│ ├── test_sdlt.py # Stamp duty calculation tests
│ └── test_yield.py # Yield estimate tests
│
├── Makefile # Shortcuts: `make dev`, `make test`, `make deploy`
├── requirements.txt # Python packages to install
├── Procfile # Tells Railway how to start the app
├── railway.toml # Railway-specific settings
└── .env.example # Template for your secret settings
Quick Start (Local Development)
# 1. Install Python 3.11+ then:
make install
# 2. Copy the example env file and fill in your values
cp .env.example .env
# 3. Start the server locally
make dev
# 4. Open the docs in your browser
# http://localhost:8000/docs
Deploy to Railway
# 1. Install Railway CLI: https://docs.railway.app/guides/cli
# 2. Login and link your project
railway login
railway link
# 3. Add a Redis plugin in the Railway dashboard
# (click "New" → "Database" → "Redis")
# 4. Set your environment variables in Railway dashboard:
# X402_FACILITATOR_URL, PAYMENT_WALLET_ADDRESS, etc.
# 5. Deploy
make deploy
Running Tests
make test
Environment Variables You Need
| Variable | What It Is | Example |
|---|---|---|
REDIS_URL | Redis connection string | redis://default:xxx@host:6379 |
X402_FACILITATOR_URL | x402 payment facilitator | https://x402.org/facilitator |
PAYMENT_WALLET_ADDRESS | Your wallet (receives payments) | 0xYourAddress... |
RATE_LIMIT_PER_MINUTE | Max requests per wallet per minute | 30 |
CACHE_TTL_SECONDS | How long to cache results | 3600 |
LOG_LEVEL | Logging verbosity | INFO |