Listing Events from Multiple Venues

Overview#

Your solution may require pulling and listing events from multiple venues. Rather than making an API call per venue, you can recieve all events at the same time through a singular request. The resulting series of events can then be used to link directly to the ParkWhiz website, render the associated location map or list view within the widget, or start a transactional flow using the API.

This method gives you the most control of information presented, including the ability to search and filter results.

Requirements#

To start, you'll need your API credentials, provided to you by your account manager, as well as a list of Arrive venue IDs from which you'd like to pull event data.

You'll need a beginner level of API knowledge to follow this walkthrough. All code examples will be provided in cURL format.

Get Events#

Base Endpoint#

As outlined in the GET /events endpoint, events can be queried by a comma-separated list of Arrive venue IDs. To retrieve a list of all upcoming events for a group of venues, call the following endpoint:

curl --location --request GET 'https://api.parkwhiz.com/v4/events?q=venue_id:$venue_ids'

To list events for sports venues in Detroit (in this case Comerica Park, Little Caeser's Arena, and Ford Field), you'd call:

curl --location --request GET 'https://api.parkwhiz.com/v4/events?q=venue_id:103,53,221175'

Which would return something similar to:

[
   {
      "id":969540,
      "name":"Green Day/Fall Out Boy/Weezer",
      "venue_id":103,
      "start_time":"2020-08-19T17:30:00.000-04:00",
      "end_time":"2020-08-19T20:30:00.000-04:00"
   },
   {
      "id":979154,
      "name":"Kenny Chesney: Chillaxification Tour",
      "venue_id":53,
      "start_time":"2020-08-15T17:00:00.000-04:00",
      "end_time":"2020-08-15T20:00:00.000-04:00"
   },
   {
      "id":988557,
      "name":"Dan + Shay: The (Arena) Tour",
      "venue_id":221175,
      "start_time":"2020-09-19T19:00:00.000-04:00",
      "end_time":"2020-09-19T22:00:00.000-04:00"
   },
   ...
]

Additional Options#

Additional options can be added to this query for further customization. Common additions include:

Searching by event name (removing all non-ASCII characters)
Filtering/sorting by date/time in ISO 8601 format
Including the URL to the event's results page on ParkWhiz
Including events with TBD times
Managing pagination (as outlined in the Pagination section of the Developer Docs)

A call with these additional options is shown below.

curl --location --request GET 'https://api.parkwhiz.com/v4/events\
    ?q=venue_id:$venue_ids name:$search_term starting_before:$start_before\
    &sort=start_time:asc\
    &fields=:default,event:site_url,event:times_tbd\
    &page=$page'

Searching by Event Name#

Including text-based search makes it easier for your users to find the events they're looking for. Fortunately, searching is available via the API.

Pre-Parse your Query

Only ASCII characters are supported in text search. It's recommended to pre-parse your query for any invalid characters. (Regex: /[^\x00-\x7F]/)

To filter results with a query (in this case, by "Detroit Tigers"), you'd call:

curl --location --request GET 'https://api.parkwhiz.com/v4/events?q=venue_id:103,53,221175%20name:Detroit%20Tigers'

Which would return something similar to:

[
    {
       "id":1001293,
       "name":"Chicago White Sox at Detroit Tigers",
       "venue_id":103,
       "start_time":"2020-06-18T13:10:00.000-04:00",
       "end_time":"2020-06-18T16:10:00.000-04:00"
    },
    {
       "id":1001294,
       "name":"Oakland Athletics at Detroit Tigers",
       "venue_id":103,
       "start_time":"2020-06-09T19:10:00.000-04:00",
       "end_time":"2020-06-09T22:10:00.000-04:00"
    },
    {
       "id":1001295,
       "name":"Kansas City Royals at Detroit Tigers",
       "venue_id":103,
       "start_time":"2020-07-03T19:10:00.000-04:00",
       "end_time":"2020-07-03T22:10:00.000-04:00"
    },
    ...
]   

Filtering/Sorting by Date/Time#

If you'd like to display events within a selected period, you can call the api with time filters.

To filter results by a start and end time, you'd call:

curl --location --request GET 'https://api.parkwhiz.com/v4/events?q=venue_id:103,53,221175%20starting_after:2020-08-19T17:30:00.000-04:00%20starting_before:2020-09-19T22:00:00.000-04:00&sort=start_time:asc'

Which would return something similar to:

[
    {
      "id":969540,
      "name":"Green Day/Fall Out Boy/Weezer",
      "venue_id":103,
      "start_time":"2020-08-19T17:30:00.000-04:00",
      "end_time":"2020-08-19T20:30:00.000-04:00"
    },
    {
      "id":1023111,
      "name":"Mötley Crüe",
      "venue_id":103,
      "start_time":"2020-08-20T16:30:00.000-04:00",
      "end_time":"2020-08-20T19:30:00.000-04:00"
    },
    {
      "id":1001318,
      "name":"Houston Astros at Detroit Tigers",
      "venue_id":103,
      "start_time":"2020-08-24T19:10:00.000-04:00",
      "end_time":"2020-08-24T22:10:00.000-04:00"
    },
    ...
]   

Including the URL to the Event's Results Page#

Rather than calling an API or rendering a widget, you can create an event linkoff to ParkWhiz.com.

To display events with their site URL, you'd call:

curl --location --request GET 'https://api.parkwhiz.com/v4/events?q=venue_id:103,53,221175&fields=:default,event:site_url'

Which would return something similar to:

[
    {
      "id":969540,
      "name":"Green Day/Fall Out Boy/Weezer",
      "venue_id":103,
      "start_time":"2020-08-19T17:30:00.000-04:00",
      "end_time":"2020-08-19T20:30:00.000-04:00",
      "site_url":"/comerica-park-parking/green-day-fall-out-boy-weezer-969540/"
    },
    {
      "id":979154,
      "name":"Kenny Chesney: Chillaxification Tour",
      "venue_id":53,
      "start_time":"2020-08-15T17:00:00.000-04:00",
      "end_time":"2020-08-15T20:00:00.000-04:00",
      "site_url":"/ford-field-parking/kenny-chesney-chillaxification-tour-979154/"
    },
    {
      "id":988557,
      "name":"Dan + Shay: The (Arena) Tour",
      "venue_id":221175,
      "start_time":"2020-09-19T19:00:00.000-04:00",
      "end_time":"2020-09-19T22:00:00.000-04:00",
      "site_url":"/little-caesars-arena-parking/dan-shay-the-arena-tour-988557/"
    },
    ...
]   

Including TBD Events#

TBD Events are events containing estimated, rather than concrete, dates in the future. Examples include playoff games and event postponements.

To display TBD events, you'd call:

curl --location --request GET 'https://api.parkwhiz.com/v4/events?q=venue_id:103,53,221175&fields=:default,event:times_tbd'

Which would return something similar to:

[
    {
      "id":969540,
      "name":"Green Day/Fall Out Boy/Weezer",
      "venue_id":103,
      "start_time":"2020-08-19T17:30:00.000-04:00",
      "end_time":"2020-08-19T20:30:00.000-04:00",
      "times_tbd":"false"
    },
    {
      "id":979154,
      "name":"Kenny Chesney: Chillaxification Tour",
      "venue_id":53,
      "start_time":"2020-08-15T17:00:00.000-04:00",
      "end_time":"2020-08-15T20:00:00.000-04:00",
      "times_tbd":"false"
    },
    {
      "id":988557,
      "name":"Dan + Shay: The (Arena) Tour",
      "venue_id":221175,
      "start_time":"2020-09-19T19:00:00.000-04:00",
      "end_time":"2020-09-19T22:00:00.000-04:00",
      "times_tbd":"false"
    }
    ...
]   

Managing Pagination#

The API returns a maximum of 100 results per API call. If your request has more than 100 results, or you'd like to limit the number of responses per call, you'll need to use Pagination.

To limit the events call to 3 responses, and display the first page of results, you'd call:

curl -i --location --request GET 'https://api.parkwhiz.com/v4/events?q=venue_id:103,53,221175&per_page=3&page=1'

Which would return something similar to:

HTTP/1.1 200 OK
Server: nginx
Status: 200 OK
Link: <https://apiv3/v4/events?page=2&per_page=10&q=venue_id%3A103%2C53%2C221175>; rel="next", <https://apiv3/v4/events?page=1&per_page=10&q=venue_id%3A103%2C53%2C221175>; rel="prev", <https://apiv3/v4/events?page=14&per_page=10&q=venue_id%3A103%2C53%2C221175>; rel="last"
X-Pagination-Total: 139
X-Pagination-Per-Page: 3
X-Pagination-Returned: 3
X-Pagination-Current-Page: 1
X-Pagination-Total-Pages: 47

[
    {
      "id":969540,
      "name":"Green Day/Fall Out Boy/Weezer",
      "venue_id":103,
      "start_time":"2020-08-19T17:30:00.000-04:00",
      "end_time":"2020-08-19T20:30:00.000-04:00"
    },
    {
      "id":979154,
      "name":"Kenny Chesney: Chillaxification Tour",
      "venue_id":53,
      "start_time":"2020-08-15T17:00:00.000-04:00",
      "end_time":"2020-08-15T20:00:00.000-04:00"
    },
    {
      "id":988557,
      "name":"Dan + Shay: The (Arena) Tour",
      "venue_id":221175,
      "start_time":"2020-09-19T19:00:00.000-04:00",
      "end_time":"2020-09-19T22:00:00.000-04:00"
    }
]   

Use the Event ID#

Linking to ParkWhiz Web#

Including the URL via the event:site_url field will provide a direct link to the event's page on ParkWhiz.com - all you need to do is add the domain from the environment you made the call in front of the returned path.

Example:

With a return of "site_url": "/madison-square-garden-parking/knotfest-roadshow-slipknot-a-day-to-remember-underoath-1045919/",

You can link to

https://www.parkwhiz.com/madison-square-garden-parking/knotfest-roadshow-slipknot-a-day-to-remember-underoath-1045919/

Rendering the Widget#

You can use the returned event ID from the API response to render a location map or list view within the widget. All you'll need is the destination-event-id parameter and a map or location-list UI component.

With a return of "id": 1045919,

Your widget URL would look like

https://widget.arrive.com/index.html?ui-components=location-list&destination-event-id=1045919

Starting the Transactional API Flow#

Similar to rendering the widget, you can start a transactional API flow using the event ID within the response. To do so, you'll pass the event_id as a GET /quotes query parameter. From the returned quotes, you can preview and book parking as per the standard transactional flow.

With a return of "id": 1045919,

Your quotes request would look like

curl --location --request GET 'https://api.parkwhiz.com/v4/quotes?q=event_id:1045919'