When building your own custom interactions with LiveWhale data, the JSON API is the best tool for getting the most complete results. Learn more about the basics of how the LiveWhale REST API works, and read on for more details pertaining specifically to the JSON API.

Version 2

In 2022 we introduced version 2 of the LiveWhale JSON API, which is organized around two central changes: implementing consistent formatting between paginated and non-paginated results, and significantly improving performance by only returning associated data (images, tags, categories, locations, etc.) when specifically requested.

You’ll still be able to use all the same REST request parameters from the previous version of the API: /tag/My Tag/ , /group/My Group/ , etc. This new approach mostly affects the results formatting and some of the display options, as explained below.

How do I start using JSON API v2?

If your LiveWhale installation has been updated recently enough, you can replace /live/json/events with /live/json/v2/events in any request URL to see the new results format. Check with LiveWhale Support if you’re interested in upgrading to JSON API v2.

To migrate your integrations to JSON API v2, you’ll need to:

1. Update your request to use /live/json/v2 rather than /live/json (eventually we’ll retire v1 and this requirement will be deprecated)
2. Change your code to always expect results in the array called “data” rather than the top-level response or, when using pagination, a “results” array
3. Check the per-item response to ensure it has all the fields you need, or request additional response_fields if needed (see below)

If your LiveWhale site was launched in Summer 2022 or after, you probably already has JSON API v2 enabled by default, so no separate /v2/ in the URL is necessary. To check, make a simple /live/json/events request and see if the response begins with the “meta” object described below.

What does a JSON API v2 result look like?

Based on some principles from the JSON API spec, the typical response to a LiveWhale JSON API v2 request will look something like this.

• meta is an object containing information about the results, including pagination, which fields were requested, and response time
• links is an object containing the URLs of the current request and commonly-needed requests (previous/next page, for instance)
• data is an array containing the results objects (events, news—whatever you’ve requested)
• errors, if present, will replace the data array

Example: /live/json/v2/events/tag/Biology/paginate/10?page=8
Events tagged “Biology” with 10 results per page (currently on page 8)

"meta": {
        "type":"events",
        "total_results": 186,
        "per_page": 10,
        "page": 8,
        "total_pages": 19,
        "response_fields": [],
        "supported_fields": ["event_types","location","tags","image","summary","contact_info","registration","last_modified","group_title","custom_fields"],
        "response_time": 0.1,
},
"links": {
        "self": "https://events.myschool.edu/live/json/v2/events/tag/Biology/paginate/10?page=8",
        "first": "https://events.myschool.edu/live/json/v2/events/tag/Biology/paginate/10?page=1",
        "prev": "https://events.myschool.edu/live/json/v2/events/tag/Biology/paginate/10?page=7"
        "next": "https://events.myschool.edu/live/json/v2/events/tag/Biology/paginate/10?page=9",
        "last": "https://events.myschool.edu/live/json/v2/events/tag/Biology/paginate/10?page=19"
},
"data": [
        {
                "id": 1,
                etc...
        },
        {
                "id": 2,
                etc...
        },
]

Find more info on JSON API v2 pagination below.

How do I customize a JSON API v2 result?

By default, JSON API v2 will only return the “basics” about your content, and any additional fields you might want to request will be shown in the supported_fields array. To include one or more of them in the response, add them to your request as response_fields, in a comma-separated list.

• /live/json/v2/events/response_fields/event_types,tags
• /live/json/v2/events/response_fields/image,summary,group_title,custom_fields
• /live/json/v2/events/response_fields/location

Note: Because of how LiveWhale saves certain image data, custom_fields will always be automatically appended to any events request that includes “image.” This is expected behavior.

When developing a custom JSON API v2 integration, you can use /response_fields/all to load data for all available fields. This can help you see what data is available, however before finalizing your integration we recommend limiting yourself to only the fields you plan to display (e.g., /response_fields/image,summary,description,event_types ), as using the all option forfeits significant performance improvements.

Understanding response_fields

In response_fields, you should only request the data that you are interested in displaying. You can still request (i.e., filter) results by group name, or event category, or tag, without needing to generate the full display-ready markup for those taxonomies.

For example,
/live/json/v2/events/tag/Biology
will return events tagged “Biology” and still has performance improvements over
/live/json/v2/events/tag/Biology/response_fields/tags

You should only use the latter if you want to, say, display all event tags in your user-facing results.

Available response_fields

Response formatting

In general, JSON API v2 response values will be formatted as:

• null for empty or absent values
• strings for text, URLs, HTML blocks, etc.
• int or float for numbers
• arrays for tags and event types

When any tag or event type field is empty, it is also returned as null rather than the empty array. This means that you can use is_null in your integrations to check for values regardless of whether that field typically returns a string, int, float, or array. For example:

"tags": ["Basketball","Women's Athletics"],
"tags_starred": null,
"tags_global": null,

How does pagination work in JSON API v2?

By default, JSON API v2 will paginate results with 100 results per page. You can use ?page=2 or the URLs in the “links” object to traverse to other pages of results.

Maximum Results

• You can change the maximum number of results with /max/{number}.

• For the best performance, we recommend limiting your request to only the number of results you will be displaying (e.g., /max/5 for a list of your next five events).

• The maximum number of results from any single API request is 1,000. If you disable pagination LiveWhale will enforce a maximum of 1,000 results, or if you try to set a page size larger than 1,000 it will be limited to 1,000 results per page.

Paginated Results

• You can change the number of results per page with /paginate/{number}.

• For the best performance, if your integration includes a “next” or “view more” link we recommend setting your page size to the number of results you plan to display before that link (e.g., /max/40/paginate/8 will query for 40 results with 8 results per page)

Disable Pagination

• You can disable pagination to return up to 1,000 results at once using /paginate/false:

"meta": {
        "type":"events",
        "total_results": 518,
        "per_page": null,
        "page": null,
        "total_pages": null,
        "response_fields": [],
        "supported_fields": ["event_types","location","tags","image","summary","contact_info","registration","last_modified","group_title","custom_fields"],
        "response_time": 0.1,
},
"links": {
        "self": "https://events.myschool.edu/live/json/v2/events/paginate/false",
        "first": null,
        "prev": null,
        "next": null,
        "last": null
},
"data": [
        etc...
]

No Results

• When your request returns no results, “data” will return an empty array:

"meta": {
        "type":"events",
        "total_results": 0,
        "per_page": 100,
        "page": 1,
        "total_pages": 0,
        "response_fields": [],
        "supported_fields": ["event_types","location","tags","image","summary","contact_info","registration","last_modified","group_title","custom_fields"],
        "response_time": 0.1,
},
"links": {
        "self": "https://events.myschool.edu/live/json/v2/events/tag/Psychology",
        "first": null,
        "prev": null,
        "next": null,
        "last": null
},
"data": []

Do I have to migrate to JSON API v2?

Eventually, yes. However, we are planning a significant overlap during which /live/json and /live/json/v2 results will both be supported. We will separately announce when v1 is being deprecated and it will be tied to a regular LiveWhale upgrade, so your developers will have ample time to test and migrate to JSON API v2.

In the meantime, depending on your API usage, we may work with you to identify high-volume or heavy-load requests in order to fast-track implementation of LiveWhale JSON API v2.

Thank you for working with us to keep this API robust, performant, and useful, and please feel free to reach out with any questions or feedback. In general we make every effort to implement changes in ways that preserve backwards-compatibility, and we acknowledge and appreciate that upgrading to this new /live/json/v2/ endpoint will require a little work. With all that in mind, we made this decision after careful consideration of its significant performance improvements over the API v1, not to mention the increased flexibility it offers for down the line.

Setting JSON API v2 as your site-wide default

If you are building integrations for the first time, or on a newly-launched site with no /live/json integrations still in use, you can set your site-wide default to set all /live/json requests to use v2 by adding the following to livewhale/core/config.php:

// The base API version to use, if left unspecified.
$GLOBALS['LIVEWHALE_CONFIG']['BASE_API_VERSION']=2;

"total_results": 594,
"per_page": 30,
"page": 1,
"total_pages": 20,
"results": [...]

Version 1

All of the RSS and iCal parameters from the LiveWhale REST API work with JSON and in addition, you may also utilize the following parameters:

• /start_date/[YYYY-MM-DD]/
• /end_date/[YYYY-MM-DD]/
• /only_today/[true or false]/
• /require_image/[true or false]/

Examples

• /start_date/2013-05-03/ Collect items beginning on this date.
• /start_date/2013-05-03%2012:00am%20America%5CLos_Angeles/ Shift a start date to a different timezone.
• /end_date/2013-05-04%2011:59pm%20America%5CLos_Angeles/ Shift an end date to a different timezone.
• /only_today/true/ Only include items from today, as reflected in the group’s or server’s timezone.
• /require_image/true/ Require that all content returned possess at least one image.

Paginating results (v1)

If you’re querying an especially large results set, you’ll improve performance by paginating the results. You can specify your pagination arg ( /paginate/30 or however many results per page you’d like) and use ?page=1 , ?page=2 , etc. to fetch subsequent pages of results.

Please note that the endpoint response is modified when pagination is turned on in order to deliver metadata about pagination:

"total_results": 594,
"per_page": 30,
"page": 1,
"total_pages": 20,
"results": [...]