Skip to main content

Hotspots REST API

Welcome to the Hotspots REST API Documentation. Hotspots is still in the very early stages of development, so expect some changes in the near future as we rapidly prototype a minimum viable product. The API is versioned, and we will make every good faith effort to not break backwards compatibility, but be aware that things may be a little fluid in these initial stages.

Access​

The API is now accessible at https://api.vibemap.com . The /api part of the path from the previous domain-less server has been removed. Now it is https://api.vibemap.com/<version>/<endpoint>/. Be sure to include the trailing slash!

Also note, if POST-ing JSON, you must also include Content-Type: application/json in the headers

A successful login will return a token that must be used in the headers of all subsequent requests, in the form of "Authorization: Token <token>"

Authentication v0.2​

Available Endpoints​

Basic​

/rest-auth/login/ (POST)​
  • email
  • password

Returns:

 {"key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx"}``
/rest-auth/logout/ (POST)​
  • email

Returns:

 {"detail": "Successfully logged out"}
/rest-auth/password/reset/ (POST)​

WORK IN PROGRESS

Needs:

  • design and copy of password reset email
  • credentials for sending email from one of our GSuite accounts or set up a provider like Mailgun/MailChimp/SendGrid
/rest-auth/password/change/ (POST)​

Allows user to change their existing password. Must provide their current password and confirm new one. The user will remain logged in after successful change.

  • old_password
  • new_password1
  • new_password2

Example:

 $ curl -X POST https://api.vibemap.com/v0.2/rest-auth/password/change/ \
     -H "Content-Type: application/json" \
     -H "Authorization: Token xxxxxxxxxxxxxxxxxx" \
     -d '{"old_password": "dfjoglsd", "new_password1": "sup3rs3cr3t", "new_password2": "sup3rs3cr3t"}'

Returns:

 {"detail": "New password has been saved."}

Registration​

/rest-auth/registration/ (POST)​

Register a new account. Will return a token if successful that can be used for all subsequent authenticated requests (i.e., should not have to log in again after successfully registering).

  • email
  • password1
  • password2

Returns:

 {"key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

Pagination​

Results are currently paginated at 50 per page by default. This can be controlled with the per_page parameter (up to 1000 records per page). The top-level keys for a list response (currently, the /events and /places endpoints) are count, next, previous, and results. The next and previous keys contain links to the next and previous pages, and the results key holds the 50 results for that page.

Example passing in per_page:

/v0.1/events/?per_page=200

Retrieve by ID​

You can retrieve a specific event or place by its ID, by appending that ID as the last path element after the places or events endpoint, as in:

/v0.1/places/022f9c2b-a5cf-4324-86c5-3eef44fd2f86/

Eventually we'll have geopolitical namespacing and prettier slugs instead of these ugly UUIDs, but that will be in a later version.

Filtering​

in_bbox​

Restrict to events within the given in_bbox parameter. Format must be in southwest_longitude,southwest_latitude,northeast_longitude,northeat_latitude (i.e., min_lon,min_lat,max_lon,max_lat). Example:

/v0.1/events/?in_bbox=-87.68368,41.9098466,-87.660770,41.9232589

It is also possible to make a point radius geographic query, by specifying a querystring of point=lon,lat&dist=<distance in meters>. Note the lon,lat ordering. Distance is always in meters (there are 1609.344 meters in one mile):

/v0.1/events/?point=-122.6757860,45.5244499&dist=500

start_date and end_date​

Both the start_date and end_date fields on events can be used in range queries, as in start_date_after=YYYY-MM-DD HH:MM&end_date_before=YYYY-MM-DD HH:MM (the hour and minutes are optional).

Searching​

Searching is currently available by using the search=term paramter, as in

/v0.1/events/?search=trivia

This currently performas only a fairly basic case-insensitive partial text search on the name and description fields on events. More advanced search functionality will be added soon.

Ordering​

Ordering is currently available on the Event name, start_date, and end_date fields, e.g.

/v0.1/events/?search=trivia&ordering=name

Prepend the field with a - for descending order, as in:

/v0.1/events/?search=trivia&ordering=-start_date

Core API​

Auto-generated Core API documentation is available at https://api.vibemap.com/v0.1/schema/