Documentation

Quick start

Get your first response in under a minute. Grab an API key from the dashboard, then make a request:

curl https://api.thepubdb.com/api/v1/pubs \
  -H "X-API-Key: $PUBDB_KEY"

The API returns JSON by default. Every response wraps results in a data array with a pagination object for page metadata.

{
  "success": true,
  "data": [
    {
      "id": "pub_0f1a3b",
      "name": "The Crown & Anchor",
      "city": "London",
      "area": "Soho",
      "postcode": "W1D 3HB",
      "country": "GB",
      "hasCaskAle": true,
      "hasSundayRoast": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 12418,
    "pages": 249,
    "hasNext": true,
    "hasPrev": false
  }
}

Authentication

Pass your API key in the X-API-Key header on every request to an authenticated endpoint.

X-API-Key: pk_developer_xxxx····

Tiers

Endpoints

The API exposes five core endpoints. All return JSON and accept query parameters for filtering and pagination.

Endpoint reference

Filtering & search

Filter pubs by amenities, location, or free-text search. All filters are query parameters on GET /api/v1/pubs.

Amenity filters

Pass any amenity as a boolean query parameter to include only matching pubs. Multiple filters are AND-ed together.

curl "https://api.thepubdb.com/api/v1/pubs?hasCaskAle=true" \
  -H "X-API-Key: $PUBDB_KEY"

Pagination

All list endpoints are paginated. Use page and limit query parameters. The pagination object in every response includes total, page, pages, hasNext, and hasPrev.

GET /pubs?page=2&limit=25

Default page size is 50. Pages are 1-indexed.

Rate limits

Rate limits are applied per API key across three windows: hourly, daily, and monthly.

Exceeded limits return a 429 Too Many Requests response. Check the X-RateLimit-Remaining header on any response to see your remaining quota.

Errors

All errors return a JSON body with a code and message field.