Localist API

The Localist API is a simple HTTP-based interface. Standard HTTP calls will return JSON your application can use. For terms of use, concepts and resources, Localist’s master API documentation can be found here: https://developer.localist.com/doc/api


Frequently Asked Questions

Is there a way for an event to appear in an API call, but does not appear on the public-facing calendar?

Yes, with a combination of event Permissions and API parameters. First, you’ll flag your event’s Permissions as Restricted: Widgets which will make your event only available in Widgets by default. Then, when building your API call, tack on the for=widget parameter.

Basic Rules

  • Localist’s API is read-only and publicly accessible.
  • Calls will pull 10 items per page by default, but can be increased to up to 100 per page (this is well-above industry standard).
  • The maximum date range that the API call pull from is 370 days from today or the start date you specify.
  • If a start date is not specified, then the API will default to only pulling event data from today.

Building an API Call

All API calls must start with http://your.custom.domain/api/2/

  • Events: http://your.custom.domain/api/2/events
  • Places: http://your.custom.domain/api/2/places
  • Groups: http:/your.custom.domain/api/2/groups
  • Departments: http:/your.custom.domain/api/2/departments

Paging: http://your.custom.domain/api/2/events?type=38570&pp=100&page=1

  • This will pull 100 results per page so to access the next 100 you would change the 1 in page=1 to 2, etc.

Date Range

  • Start and End date: http://your.custom.domain/api/2/events?type=38570&pp=100&page=1& start=2014-10-01&end=2014-11-01
  • Today + number of future days: http://your.custom.domain/api/2/events?days=90 (the maximum is 370 days).

API Token

Since the Localist API is publicly accessible, only public info is available. Things that aren’t public surround user data, so for example, who is attending an event. A token tells the API, “this is a trusted person”, and allows them to access the private data — think of this like a password. To give someone a token, you’ll need to follow the steps below:

  • Navigate to the Admin Dash > Settings > Apps
  • On the righthand side of the page, click ‘Add App

    Fill out Name (this can be internal, like ‘Localist Integration’) and App Website (the URL where the data will be used or your main domain)

  • Click ‘Save Changes
  • Click ‘Manage Access Tokens‘ in the top right corner

    +Create Access Token > Fill out details > Create Token

  • You’ll see the token on the resulting page, which you can pass along to the person who needs access to private data in the API