Pubbers API

This API allows clients to search for pubs, retrieve individual pub details, filter pubs by distance, and sort or paginate results. All requests require an API key in the headers.

Authentication

Include your API key in the request header:

x-api-key: your-api-key

Base URL

GET /api/v1/pubs/

---

Endpoints

1. Get Pub by ID

Returns a single pub with full details and rankings.

GET /api/v1/pubs/?pubid=123

Parameters

Name	Type	Description
pubid	string	UID of the pub

Response

{
    "results": [{ ... pub data ... }],
    "page": 1,
    "total_pages": 1,
    "total_results": 1,
    "total_pubs": 123
}

2. Standard Search

Returns a paginated list of pubs matching the search query.

GET /api/v1/pubs/?search=London&page=1&amount=20&sort=name&order=asc&rated=true

Query Parameters

Name	Type	Description
search	string	Search term for pub name or location
page	integer	Page number (default: 1)
amount	integer	Items per page (1–100, default: 20)
sort	string	Sort by: name, location, review_count, beer, atmos, fengshui, service, toilets, total
order	string	asc (default) or desc
rated	boolean	Only return pubs with ratings (true/false)

Response

{
    "results": [ ... ],
    "page": 1,
    "total_pages": 5,
    "total_results": 100,
    "total_pubs": 123,
    "sort": "name",
    "order": "ASC",
    "only_rated": true
}

3. Distance-Based Search

Returns pubs within a given distance from a lat/lng point, sorted by proximity.

GET /api/v1/pubs/?search=London&lat=51.5&lng=-0.12&distance=5&rated=true&marker=The%20Anchor

Additional Parameters

Name	Type	Description
lat	float	Latitude of search point
lng	float	Longitude of search point
distance	float	Search radius in kilometers
marker	string	(Optional) Pub name to exclude from results

Response

{
    "results": [ ... ],
    "total_results": 10,
    "total_pubs": 123,
    "total_pages": 1,
    "sort": "distance",
    "order": "ASC",
    "only_rated": true,
    "distance": 5,
    "lat": 51.5,
    "lng": -0.12
}

---

Pub Object

Fields returned in each pub object:

• UID: Unique identifier
• name: Pub name
• location: General area
• trading: Trading status
• latitude, longitude: Geo coordinates
• common_category: Most frequently reviewed category
• beer, atmos, fengshui, service, toilets: Average ratings (0-10)
• total: Composite average rating
• review_count: Number of reviews
• distance: Distance from search location (if applicable)
• rankings: Object with rank per metric (if applicable)

Errors

Status	Message
400	Missing required parameter (pubid or search)
401	API key required
403	Invalid or revoked API key
404	Pub not found
500	Internal server error / database query error