Public API

Base URL & Rate Limits

All endpoints are relative to:

https://yolist.uk

The public API is rate limited to 60 requests per minute per IP address. Rate limit headers are included in every response:

x-ratelimit-limit: 60
// No x-ratelimit-remaining header on public endpoints — check 429 status

For higher rate limits and additional fields, apply for a free API key at /developers.

GET /api/v1/businesses

Returns a paginated list of businesses. All parameters are optional.

Query parameters

Example request

curl "https://yolist.uk/api/v1/businesses?city=london&category=plumbers&page=1&limit=20"

Example response

{
  "businesses": [
    {
      "id": "clx1abc...",
      "name": "Acme Plumbing Ltd",
      "slug": "acme-plumbing-london",
      "category": "plumbers",
      "city": "London",
      "rating": 4.7,
      "reviewCount": 38,
      "phone": "020 ****",
      "website": "https://acmeplumbing.co.uk",
      "isVerified": true
    }
  ],
  "total": 142,
  "page": 1,
  "pages": 8
}

Response fields

GET /api/v1/businesses/:slug

Returns full details for a single business by its slug. Phone and email are only returned for claimed businesses. Returns 404 if the business is not found or not approved.

URL parameters

Example request

curl "https://yolist.uk/api/v1/businesses/acme-plumbing-london"

Example response

{
  "id": "clx1abc...",
  "name": "Acme Plumbing Ltd",
  "slug": "acme-plumbing-london",
  "shortDescription": "Emergency plumbing in London",
  "description": "Full service plumbing company ...",
  "category": "Plumbers",
  "categorySlug": "plumbers",
  "city": "London",
  "citySlug": "london",
  "address": {
    "line1": "12 High Street",
    "line2": null,
    "postcode": "EC1A 1BB"
  },
  "coordinates": { "lat": 51.5074, "lng": -0.1278 },
  "phone": "020 7946 0958",
  "email": "hello@acmeplumbing.co.uk",
  "website": "https://acmeplumbing.co.uk",
  "rating": 4.7,
  "reviewCount": 38,
  "isVerified": true,
  "isPremium": false,
  "photos": [
    { "url": "https://...", "caption": "Our van", "isCover": true }
  ],
  "openingHours": [
    { "day": "MONDAY", "openTime": "08:00", "closeTime": "18:00", "isClosed": false, "is24Hours": false }
  ]
}

Code Examples

JavaScript (fetch)

// JavaScript / fetch
const res = await fetch('https://yolist.uk/api/v1/businesses?city=manchester&limit=10')
const { businesses, total, pages } = await res.json()
console.log(`Found ${total} businesses across ${pages} pages`)
businesses.forEach(b => console.log(b.name, b.rating))

Python (requests)

# Python / requests
import requests

r = requests.get('https://yolist.uk/api/v1/businesses', params={
    'city': 'birmingham',
    'category': 'electricians',
    'page': 1,
    'limit': 20,
})
data = r.json()
for biz in data['businesses']:
    print(biz['name'], biz['rating'])

Error Responses