API Documentation

Quick Start

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.townbrief.co.uk/api/v1/planning

Authentication

All API requests require authentication using an API key. Include your API key in one of two ways:

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Rate Limits

Rate limits vary by subscription tier:

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Endpoints

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.townbrief.co.uk/api/v1/planning?town=guildford&limit=10"

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.townbrief.co.uk/api/v1/roadworks?town=guildford"

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.townbrief.co.uk/api/v1/events?town=guildford"

Response Format

All endpoints return JSON with the following structure:

{
  "data": [
    {
      "id": "clx123...",
      "title": "Planning Application: 2024/0123",
      "summary": "Planning application 2024/0123 at 123 High Street...",
      "category": "planning",
      "publishedAt": "2024-12-15T10:30:00.000Z",
      "sourceUrl": "https://www.planning.data.gov.uk/...",
      "town": {
        "name": "Guildford",
        "slug": "guildford",
        "council": "Guildford Borough Council"
      },
      "source": {
        "name": "Planning Data Platform (UK Government)",
        "url": "https://www.planning.data.gov.uk"
      }
    }
  ],
  "meta": {
    "total": 45,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Error Responses

{
  "error": "Missing API key. Provide it in Authorization header..."
}

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Limit: 10 per minute.",
  "retryAfter": 45
}

Code Examples

const API_KEY = 'your-api-key'
const BASE_URL = 'https://www.townbrief.co.uk/api/v1'

async function getPlanningApplications(town) {
  const url = new URL(`${BASE_URL}/planning`)
  if (town) url.searchParams.set('town', town)
  
  const response = await fetch(url.toString(), {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
    },
  })
  
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`)
  }
  
  return response.json()
}

// Usage
const data = await getPlanningApplications('guildford')
console.log(data.data) // Array of planning applications

import requests

API_KEY = 'your-api-key'
BASE_URL = 'https://www.townbrief.co.uk/api/v1'

def get_planning_applications(town=None):
    url = f'{BASE_URL}/planning'
    headers = {'Authorization': f'Bearer {API_KEY}'}
    params = {}
    if town:
        params['town'] = town
    
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

# Usage
data = get_planning_applications('guildford')
print(data['data'])  # List of planning applications