Developer API v1
REST, JSON, paginated. Authenticate with the
X-API-Key header, Authorization: Bearer <key>, or ?api_key=.
Get a key
curl -X POST https://restaurantsnearme.co.za/api/v1/keys \
-H 'Content-Type: application/json' \
-d '{"email": "[email protected]"}'Returns your key once — store it. Free plan:
1,000 requests/day. Quota headers
X-RateLimit-Limit / X-RateLimit-Remaining come back on every call.
Endpoints
| Endpoint | Description |
|---|---|
GET /api/v1/stats | Directory-wide counts |
GET /api/v1/outlets | List outlets. Filters: q, brand, province,
city, amenity, has_phone, has_website, has_email, has_hours. Paging:
page, per_page (max 200) |
GET /api/v1/outlets/{id} | Single outlet, all fields |
GET /api/v1/brands | List brands with outlet counts. q, page, per_page |
GET /api/v1/brands/{slug} | Brand detail + province breakdown + socials |
GET /api/v1/provinces | Province summaries |
GET /api/v1/provinces/{slug} | Province detail: top brands & cities |
GET /api/v1/health | Liveness (no auth) |
Example
curl 'https://restaurantsnearme.co.za/api/v1/outlets?brand=KFC&province=Gauteng&has_phone=1&per_page=5' \
-H 'X-API-Key: sad_…'{
"data": [ { "id": 123, "brand": "KFC", "name": "KFC Sandton", … } ],
"meta": { "total": 212, "page": 1, "per_page": 5, "pages": 43,
"quota": { "plan": "free", "used_today": 7, "remaining_today": 993 } }
}Errors
Non-2xx responses return {"error": {"status", "message"}} —
401 bad key · 429 daily quota exceeded · 404 not found.