Using the Transactional API

This walkthrough provides tutorials on the standard API calls used within our service.

Overview#

Arrive provides a transactional API that makes it easy for any partner to programmatically find and book parking. Below we'll walk through some key concepts and common API flows to help you get started. For more detailed information, be sure to read our full API reference.

Introduction#

Base URLs#

Sandbox:

  • API: https://api-sandbox.parkwhiz.com/
  • Website: https://sandbox.parkwhiz.com

Production:

  • API: https://api.parkwhiz.com/
  • Website: https://www.parkwhiz.com

Note that the websites can be co-branded for brand loyalty as well.

Authentication#

All transactional API endpoints require authentication; thus you'll need an access token for every request. Tokens can be created using a token grant flow. Here's an example of creating an access token with the client_credentials grant type in our sandbox environment:

curl http://api.sandbox.parkwhiz.com/v4/oauth/token \
-d grant_type=client_credentials \
-d client_id={YOUR-CLIENT-ID} \
-d client_secret={YOUR-CLIENT-SECRET} \
-d scope=partner

This will return the following response:

{
"access_token":"new-access-token-for-you-to-use",
"token_type":"Bearer",
"expires_in":31557600,
"scope":"partner",
"created_at":1567098455
}

This token can be used with the endpoints defined in our API docs, including the example requests below.

Examples#

Perform search and book on invoice#

Search using coordinates

The following request will return a list of locations that utilize mobile parking passes within a half mile of the specified latitude and longitude:

curl "http://api.sandbox.parkwhiz.com/v4/quotes/?q=coordinates:41.8788323,-87.6451561%20distance:.5&start_time=2020-10-23T12:45&end_time=2020-10-23T18:45&distance=5&returns=offstreet_bookable_mobile&per_page=10&page=1" -H 'Authorization: Bearer {YOUR-ACCESS-TOKEN}'

This will return a set of results similar to below:

[
{
"location_id":"9651",
"start_time":"2020-10-23T12:45:00.000-05:00",
"end_time":"2020-10-23T18:45:00.000-05:00",
"min_start":"2020-10-23T12:45:00.000-05:00",
"max_end":"2020-10-24T12:45:00.000-05:00",
"distance":{
"straight_line":{
"meters":181,
"feet":596
}
},
"purchase_options":[
{
"id":"a21c9d64-3b9e-421c-a626-96caee538a56",
"start_time":"2020-10-23T12:45:00.000-05:00",
"end_time":"2020-10-23T18:45:00.000-05:00",
"min_start":"2020-10-23T12:45:00.000-05:00",
"max_end":"2020-10-24T12:45:00.000-05:00",
"base_price":{
"USD":"10.00"
},
"price":{
"USD":"10.00"
},
"display":{
"price":"price"
},
"pricing_segments":[
{
"id":458430,
"start_time":"2020-10-23T12:45:00.000-05:00",
"end_time":"2020-10-23T18:45:00.000-05:00",
"event":{
},
"space_availability":{
"status":"available"
},
"pricing_type":"TransientPricing"
}
],
"space_availability":{
"status":"available"
},
"validation":{
"require_license_plate":false,
"validation_steps":[
{
"instructions":"Scan ParkWhiz Pass at entry gate",
"icon":{
"path":"https://d2uqqhmijd5j2z.cloudfront.net/files/77143/original/validation-icons-11.png?1453405538"
}
},
{
"instructions":"Park in any spot not marked \"Reserved\"",
"icon":{
"path":"https://d2uqqhmijd5j2z.cloudfront.net/files/77149/original/validation-icons-28.png?1453405541"
}
},
{
"instructions":"Upon departure, scan ParkWhiz Pass at exit gate",
"icon":{
"path":"https://d2uqqhmijd5j2z.cloudfront.net/files/77155/original/validation-icons-11.png?1453405545"
}
}
]
},
"disclaimers":[
"pow"
],
"amenities":[
{
"name":"Unobstructed",
"key":"unobstructed",
"description":"Guaranteed to be unobstructed",
"enabled":true,
"visible":true
},
{
"name":"Attended",
"key":"attended",
"description":"Attended",
"enabled":false,
"visible":true
},
{
"name":"Covered",
"key":"indoor",
"description":"Covered",
"enabled":false,
"visible":true
},
{
"name":"Security",
"key":"security",
"description":"Security",
"enabled":false,
"visible":false
},
{
"name":"Valet",
"key":"valet",
"description":"Valet",
"enabled":false,
"visible":false
},
{
"name":"Restrooms",
"key":"restrooms",
"description":"Restrooms",
"enabled":false,
"visible":false
},
{
"name":"Reentry Allowed",
"key":"reentry",
"description":"Reentry allowed",
"enabled":false,
"visible":true
},
{
"name":"Accessible",
"key":"handicap",
"description":"Accessible",
"enabled":false,
"visible":true
},
{
"name":"Electric Car Charging",
"key":"vehicle_charging",
"description":"Electric Car Charging",
"enabled":false,
"visible":false
},
{
"name":"Printed Pass",
"key":"printed_pass",
"description":"Printed pass",
"enabled":false,
"visible":false
}
],
"price_advisory":"None",
"curation_score":142725.35676361324,
"_links":{
"site:purchase":{
"href":"/find_and_book/?location_id=9651\u0026start_time=2020-10-23T12:45\u0026end_time=2020-10-23T18:45"
},
"curies":[
{
"name":"site",
"href":"https://www.parkwhiz.com/{rel}",
"templated":true
}
]
}
}
],
"seller_id":1636,
"quote_type":"transient",
"name":"",
"_embedded":{
"pw:location":{
"id":"9651",
"name":"Foresee, LLC",
"address1":"208 S. Jefferson Ave",
"city":"Chicago",
"state":"IL",
"country":"US",
"currency":"USD",
"postal_code":"60661",
"entrances":[
{
"coordinates":[
41.8788333,
-87.64296689999999
]
}
],
"photos":[
{
"position":0,
"sizes":{
"original":{
"URL":"https://dbmgns9xjyk0b.cloudfront.net/placeholder.png",
"width":1620,
"height":1080
},
"logo":{
"URL":"https://dbmgns9xjyk0b.cloudfront.net/placeholder.png",
"width":150,
"height":100
},
"gallery":{
"URL":"https://dbmgns9xjyk0b.cloudfront.net/placeholder.png",
"width":800,
"height":533
},
"gallery_thumb":{
"URL":"https://dbmgns9xjyk0b.cloudfront.net/placeholder.png",
"width":100,
"height":67
},
"search_thumb":{
"URL":"https://dbmgns9xjyk0b.cloudfront.net/placeholder.png",
"width":130,
"height":130
},
"res_ticket":{
"URL":"https://dbmgns9xjyk0b.cloudfront.net/placeholder.png",
"width":300,
"height":200
},
"hub_frontpage":{
"URL":"https://dbmgns9xjyk0b.cloudfront.net/placeholder.png",
"width":300,
"height":300
}
}
}
],
"_links":{
"self":{
"href":"/locations/9651"
},
"pw:quotes":{
"href":"/quotes?q=location_id:9651\u0026start_time=2020-10-23T12:45\u0026end_time=2020-10-23T18:45"
},
"pw:reviews":{
"href":"/locations/9651/reviews"
},
"site:purchase":null,
"curies":[
{
"name":"pw",
"href":"https://api.parkwhiz.com/v4/{rel}",
"templated":true
}
]
}
}
}
},
...

With these results, you can choose to send someone to checkout on web using the site:purchase attribute, or book on invoice. For this example, we'll walk through the latter.

Book on invoice

Booking on invoice is as it sounds -- once a request is made to perform a booking, a parking pass is issued and payment will be reconciled between Arrive and the distribution partner at a later date. Note that we limit this capability to partners that process their own payments, and where we have a strategic relationship with.

Here's an example of an API call to book on invoice using the result above:

curl http://api.sandbox.parkwhiz.com/v4/bookings/ -H 'Authorization: Bearer {YOUR-ACCESS-TOKEN}' \
-d quote_id=a21c9d64-3b9e-421c-a626-96caee538a56 \
-d final_price=10.00 \
-d customer_first_name=Jeff \
-d customer_last_name=Judge \
-d customer_email=jjudge@arrive.com \
-d invoice=true

This will return a booking object:

[
{
"id":84044575,
"customer_id":2132090,
"start_time":"2020-10-23T12:45:00.000-05:00",
"end_time":"2020-10-24T12:45:00.000-05:00",
"price_paid":{
"USD":"10.0"
},
"full_price":{
"USD":"10.0"
},
"purchased_at":"2019-08-29T18:31:19.863Z",
"type":"transient_booking",
"on_demand":false,
"cancellable":true,
"_embedded":{
"pw:location":{
"_links":{
"self":{
"href":"/locations/9651"
},
"pw:reviews":{
"href":"/locations/9651/reviews"
},
"pw:quotes":{
"href":"/quotes?q=location_id:9651\u0026start_time=2019-08-29T18:31:19+00:00\u0026end_time=2019-08-29T21:31:19+00:00"
},
"curies":[
{
"name":"pw",
"href":"https://api.parkwhiz.com/v3/{rel}",
"templated":true
}
]
}
},
"pw:parking_pass":{
"id":84044575,
"status":"active",
"start_time":"2020-10-23T12:45:00.000-05:00",
"end_time":"2020-10-24T12:45:00.000-05:00",
"pass_type":"transient",
"amenities":[
{
"name":"Unobstructed",
"description":"Guaranteed to be unobstructed",
"key":"unobstructed",
"enabled":true,
"visible":true
},
{
"name":"Tailgating",
"description":"Tailgating",
"key":"tailgate",
"enabled":false,
"visible":false
},
{
"name":"Reentry Allowed",
"description":"Reentry allowed",
"key":"reentry_allowed",
"enabled":false,
"visible":true
},
{
"name":"Attended",
"description":"Attended",
"key":"attended",
"enabled":false,
"visible":true
},
{
"name":"Valet",
"description":"Valet",
"key":"valet",
"enabled":false,
"visible":false
},
{
"name":"Restrooms",
"description":"Restrooms",
"key":"restroom",
"enabled":false,
"visible":false
},
{
"name":"Covered",
"description":"Covered",
"key":"indoor",
"enabled":false,
"visible":true
},
{
"name":"Security",
"description":"Security",
"key":"security",
"enabled":false,
"visible":false
},
{
"name":"RVs Allowed",
"description":"RVs allowed",
"key":"rv",
"enabled":false,
"visible":false
},
{
"name":"Accessible",
"description":"Accessible",
"key":"handicap",
"enabled":false,
"visible":true
},
{
"name":"Free Shuttle",
"description":"Free Shuttle",
"key":"shuttle",
"enabled":false,
"visible":false
},
{
"name":"Free Shuttle To Venue",
"description":"Free shuttle to venue",
"key":"shuttle_to_venue",
"enabled":false,
"visible":false
},
{
"name":"Free Shuttle From Venue",
"description":"Free shuttle from venue",
"key":"shuttle_from_venue",
"enabled":false,
"visible":false
},
{
"name":"Electric Car Charging",
"description":"Electric Car Charging",
"key":"vehicle_charging",
"enabled":false,
"visible":false
},
{
"name":"Mobile Pass",
"description":"Mobile pass",
"key":"eticket",
"enabled":true,
"visible":false
},
{
"name":"Price Premium",
"description":"Price Premium",
"key":"price_premium",
"enabled":false,
"visible":false
},
{
"name":"Has Gallery",
"description":"Has gallery",
"key":"has_gallery",
"enabled":false,
"visible":false
},
{
"name":"Lowest Price Guaranteed",
"description":"Lowest price guaranteed",
"key":"lowest_price_guarantee",
"enabled":false,
"visible":false
},
{
"name":"ParkWhiz Perk",
"description":"ParkWhiz Perk",
"key":"parkwhiz_perk",
"enabled":false,
"visible":false
},
{
"name":"Printed Pass",
"description":"Printed Pass",
"key":"printed_pass",
"enabled":false,
"visible":false
}
],
"seller_id":1636,
"active":true,
"disclaimers":"pow",
"price_paid":{
"USD":10.0
},
"full_price":{
"USD":10.0
},
"validation":{
"display_message":"Your validation method is your scan code.",
"instructions":"boom",
"require_license_plate":false,
"require_printout":false,
"steps":[
{
"instructions":"Scan ParkWhiz Pass at entry gate",
"icon":{
"path":"https://d36ck51ol93c7a.cloudfront.net/files/77143/icon/validation-icons-11.png?1453405538"
}
},
{
"instructions":"Park in any spot not marked \"Reserved\"",
"icon":{
"path":"https://d36ck51ol93c7a.cloudfront.net/files/77149/icon/validation-icons-28.png?1453405541"
}
},
{
"instructions":"Upon departure, scan ParkWhiz Pass at exit gate",
"icon":{
"path":"https://d36ck51ol93c7a.cloudfront.net/files/77155/icon/validation-icons-11.png?1453405545"
}
}
],
"scan_code":{
"code":"84044575",
"format":"QR",
"qr_error_correction_level":"L"
},
"gate_technologies":[
],
"display":{
"pass_number":"required",
"scan_code":"required",
"license_plate":"hidden",
"full_price":"hidden",
"customer_name":"hidden",
"pricing_codes":"hidden",
"gate_button":"hidden",
"print_instructions":"hidden"
}
},
"reseller_pass":false,
"_embedded":{
"pw:location":{
"_links":{
"self":{
"href":"/locations/9651"
},
"pw:reviews":{
"href":"/locations/9651/reviews"
},
"pw:quotes":{
"href":"/quotes?q=location_id:9651\u0026start_time=2019-08-29T18:31:19+00:00\u0026end_time=2019-08-29T21:31:19+00:00"
},
"curies":[
{
"name":"pw",
"href":"https://api.parkwhiz.com/v3/{rel}",
"templated":true
}
]
}
},
"pw:seller":{
"_links":{
"curies":[
{
"name":"pw",
"href":"https://api.parkwhiz.com/v3/{rel}",
"templated":true
}
]
}
},
"pw:partner":{
"_links":{
"curies":[
{
"name":"pw",
"href":"https://api.parkwhiz.com/v3/{rel}",
"templated":true
}
]
}
},
"pw:add_ons":[
]
}
},
"pw:customer":{
"email":"jjudge@arrive.com",
"first_name":"Jeff",
"last_name":"Judge",
"marketing_allowed":false,
"_links":{
}
},
"pw:add_ons":[
]
},
"_links":{
"self":{
"href":"/bookings/84044575"
},
"pw:location":{
"href":"/locations/9651"
},
"curies":[
{
"name":"pw",
"href":"https://api.parkwhiz.com/v3/{rel}",
"templated":true
}
]
}
}
]

You can also configure the API to return a parking pass URL and authorization code, which enables anonymous access to the pass itself. See the booking API docs for more details.

Fetch events with parking availability#

This example enables a partner to make an API request to return parking availability and purchase options near a venue. Each option includes a URL for an user to complete their purchase on parkwhiz.com.

Find venue

First, let's find events for a venue using its Arrive ID. You can search for venue by name using the venues endpoint, and the q parameter:

GET /v4/venues?q=name:United Center

A partial response:

[
{
"id": 7,
"name": "United Center",
"address1": "1901 W. Madison St.",
"city": "Chicago",
"state": "IL",
"postal_code": "60612",
"_links": {
"self": {
"href": "/venues/7"
},
"pw:events": {
"href": "/venues/7/events"
},
"pw:quotes": {
"href": "/quotes?q=venue_id:7"
},
"curies": [
{
"name": "pw",
"href": "https://api.parkwhiz.com/v3/{rel}",
"templated": true
}
]
}
},
...

Retrieve events and parking availability

Now, we can retrieve events for that specific venue using the events endpoint. You can use the fields parameter to customize the fields returned in the response:

GET /v4/venues/7/events/?&pretty=true&fields=venue::default,event::default,event:availability,site_url

Partial response:

[
{
"id": 758500,
"name": "Carrie Underwood",
"venue_id": 7,
"start_time": "2019-10-29T19:00:00.000-05:00",
"end_time": "2019-10-29T22:00:00.000-05:00",
"site_url": "/united-center-parking/carrie-underwood-758500/",
"availability": {
"approximate_low": 20.0,
"approximate_high": 25.0,
"available": 5
},
"_links": {
"self": {
"href": "/events/758500"
},
"pw:venue": {
"href": "/venues/7"
},
"pw:quotes": {
"href": "/quotes?q=event_id:758500"
},
"curies": [
{
"name": "pw",
"href": "https://api.parkwhiz.com/v3/{rel}",
"templated": true
}
]
}
},
...

Using the availability element above, we can see that there are five parking options available priced between $20-25 for the event.

Handoff to web for checkout

Now, we can use the site_url element in the response above to grab the URL the user can use to checkout:

https://www.parkwhiz.com/united-center-parking/carrie-underwood-758500/

Finally, an affiliate code can be added to the URL to properly track bookings and co-brand the landing page.

Last updated on by David Gwizdala