Skip to main content

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>
Token vs Bearer

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:

ParameterTypeDefaultDescription
pageinteger1Page number to retrieve.
page_sizeinteger50 (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 (or null).
  • previous: URL to fetch the previous page of results (or null).

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 CodeMeaning
200 OKRequest succeeded.
400 Bad RequestInvalid query parameter or missing required field.
401 UnauthorizedMissing or invalid API token on a protected endpoint.
403 ForbiddenValid token, but insufficient permissions for the resource.
404 Not FoundThe requested resource or slug does not exist.
429 Too Many RequestsRate limit exceeded. Back off and retry.
500 Internal Server ErrorServer error. Contact support if persistent.