REST API Overview
Build custom apps, GIS workflows, and partner integrations against the Vibemap platform.
The Vibemap REST API provides access to verified places, community events, curated lists, and district themes. It powers Vibemap's web widgets, mobile applications, and partner integrations.
Service Endpoints & Versioning
- Base URL:
https://api.vibemap.com - Current Version:
v0.3(prefixed on all endpoints, e.g./v0.3/search/places/)
All requests should be made over HTTPS. Responses are JSON (application/json) or iCalendar feeds (text/calendar).
Authentication
Most read-only endpoints (including Search, Places, Events, Themes, and Boundaries) support anonymous public access without an API key or token.
When authentication is required (e.g. for accessing partner-scoped data, private previews, or elevated rate limits), use DRF Knox Token Authentication via the Authorization header:
Authorization: Token <YOUR_API_TOKEN>
Vibemap API uses Django REST Knox tokens prefixed with Token (not Bearer ).
To obtain an API token for your organization, contact support@vibemap.com.
Response Structure & GeoJSON
Resource listings for Places and Events return a standard paginated wrapper where results contains an RFC 7946 GeoJSON FeatureCollection:
{
"count": 1413,
"next": "https://api.vibemap.com/v0.3/places/?boundary=clermont&page=2&page_size=10",
"previous": null,
"results": {
"type": "FeatureCollection",
"features": [
{
"id": "c76d29b2-32a1-4384-9036-7c6dfb4c2b9a",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-84.1824, 39.0743]
},
"properties": {
"name": "East Fork State Park",
"slug": "east-fork-state-park",
"address": "3294 Elklick Rd, Bethel, OH 45106",
"categories": ["outdoors", "parks"],
"vibes": ["scenic", "relaxing"],
"is_closed": false
}
}
]
}
}
Pagination & Limits
List endpoints accept standard pagination parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number to retrieve. |
page_size | integer | 50 (or 150) | Number of records per page. Search endpoints support up to 1000. |
The envelope includes pagination links:
count: Total matching records.next: URL to fetch the next page of results (ornull).previous: URL to fetch the previous page of results (ornull).
Rate Limits & Throttling
Public endpoints are protected against abuse via IP-based throttles:
- Anonymous requests: 60 requests / minute per IP.
- Authenticated requests: 120 requests / minute per user token.
If you exceed these limits, the API returns HTTP 429 Too Many Requests with a Retry-After header.
CORS & Caching
- CORS:
Access-Control-Allow-Origin: *is enabled across all public endpoints, allowing direct browser calls from client-side JavaScript. - Cache-Busting: For near-real-time updates or to bypass intermediate CDN caching, append a timestamp query parameter:
?cache_bust=<timestamp>.
Error Handling
Standard HTTP status codes are used:
| Status Code | Meaning |
|---|---|
200 OK | Request succeeded. |
400 Bad Request | Invalid query parameter or missing required field. |
401 Unauthorized | Missing or invalid API token on a protected endpoint. |
403 Forbidden | Valid token, but insufficient permissions for the resource. |
404 Not Found | The requested resource or slug does not exist. |
429 Too Many Requests | Rate limit exceeded. Back off and retry. |
500 Internal Server Error | Server error. Contact support if persistent. |