Arrive API v4

The Arrive API is organized around REST. Our API has resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can view an API Changelog here.

Please contact dev@arrive.com with any questions or concerns.

Introduction

Base URL

The API is available at https://api.parkwhiz.com/v4/. A sandbox API is also available for testing at https://api-sandbox.parkwhiz.com/v4/.

Authentication

Overview

Many resources on the Arrive API are only accessible if the requester has proper authorization. The way to access endpoints that require authentication is to use an OAuth2 access token as an authorization header (e.g. Authorization Bearer OAUTH_TOKEN). The POST /oauth/token endpoint can be used to issue a token as documented in the grant flows below.

Grant Flows

There are different types of "grant flows" that can be followed when requesting a token. Each one has a different use case and target user, so care should be taken to ensure the right grant flow method is used for the right situation. These methods are:

Grant Flow Name grant_type parameter value Use Case
Client credentials grant_type=client_credentials Used by an app or trusted partner when user specific information doesn't need to be retrieved. This is most appropriate for requests not associated with user data like GET /quotes. To access or modify user data (e.g. GET /bookings, GET /accounts/me) you must use a password grant or authorization code grant.
Public token n/a Used by an app to obtain a client credentials token in cases where embedding your client secret is not desirable (e.g. on a mobile app). Your access token will be limited in the same ways a regular client credentials token is. NOTE: your partner credentials will need permission in order to use this endpoint.
Password

Verification Code
grant_type=password Used when user information is known and the client credentials need to be concealed, such as in a client side web application, and specific user information needs to be accessed or modified.
Authorization code grant_type=authorization_code Used by an app or a trusted partner when they need to access or modify user specific information on behalf of a user but do not have access to the user's information to use a password grant.
Refresh token grant_type=refresh_token Used to refresh a token to prevent expiry. Cannot be used to regenerate a token generated from the client credentials flow.

Further information about each of these grant flows are listed in their respective sections:

Generating A Token with Client Credentials

An Arrive-authorized client application can request a token for a user by posting to /oauth/token with the query or body parameter grant_type=client_credentials. The Arrive-issued client_id and client_secret must be specified as query parameters, body parameters, or in an Authorization: HTTP Basic Auth header.

For example:

POST /oauth/token?grant_type=client_credentials&client_id=ASSIGNED_CLIENT_ID_1234&client_secret=ASSIGNED_CLIENT_SECRET_1234&scope=public

which will yield a response like:

{
  "access_token": "new_token_12345",
  "token_type": "bearer",
  "expires_in": 31557600,
  "scope": "public",
  "created_at": 1486143527
}
  • expires_in gives the number of seconds until the token expires (tokens expire a year after they are granted).
  • scope the authorization scope given to this token. See the scope section.
  • created_at when the token was created as a UNIX timestamp.

Use of this token via Authorization: Bearer OAUTH_TOKEN will uniquely and securely identify the client account. Note that the client credentials token is inherently limited in what it can do with respect to user accounts. The token is not associated with a user so GET /accounts/me will not retrieve any user information. Likewise, user information in general cannot be modified or retrieved by this token. Requests not associated with user information like GET /quotes are appropriate for this token.

Generating A Public Token

In cases where you do not wish to provide the client secret (e.g. in a mobile app), you can obtain a public client credentials token by posting to the /oauth/public_token endpoint. This token will behave in much the same way a regular client credentials token does except it is limited to the mobile and public scopes. If the scope parameter is not explicitly set, public will be assumed. NOTE: your partner credentials will need permission in order to use this endpoint.

For example:

POST /oauth/public_token?client_id=ASSIGNED_CLIENT_ID_1234&scope=public

which will yield a response identical to the client credentials token:

{
  "access_token": "new_token_12345",
  "token_type": "bearer",
  "expires_in": 31557600,
  "scope": "public",
  "created_at": 1486143527
}

Generating A Token With Password Grant Type

Generating a token via client credentials is not recommended for all circumstances. For example, in a client-side web application where requests are exposed to the user, using grant_type=client_credentials would be insecure. Additionally, as stated in the client credentials section, the token generated from that flow cannot access or modify user data.

Another way to generate a token is through using grant_type=password which uses parameters based on the attributes of the user who's being authenticated. This grant flow allows the holder of the token to access and modify the user information associated with the customer_email and customer_password used in the request.

An example request:

POST oauth/token?grant_type=password&scope=public&customer_email=you@yourdomain.com&customer_password=yourSecurePassword

with response:

{
  "access_token": "YOUR_ACCESS_TOKEN_1234",
  "token_type": "bearer",
  "expires_in": 31557600,
  "refresh_token": "YOUR_REFRESH_TOKEN_1234",
  "scope": "public",
  "created_at": 1486157828
}

Generating A Token With Password Grant Type For Sing In By Phone

This section extends the regular grant_type=password flow with authenticating the user by an account verification code. Account verification codes can be obtained using a previously verified phone number.

Generate token through using grant_type=password which uses parameters based on the attributes of the user who's being authenticated. This grant flow allows the holder of the token to access and modify the user information associated with the country_code, phone_number, and verification_code used in the request. account_verification_code is a one time use access code that can be requested by hitting POST /account_verification_codes endpoint.

Note: If the country_code parameter is not sent 1 is assumed.

An example request:

POST oauth/token?grant_type=password&scope=public&country_code=1&phone_number=1234567890&verification_code=123456

with response:

{
  "access_token": "YOUR_ACCESS_TOKEN_1234",
  "token_type": "bearer",
  "expires_in": 31557600,
  "refresh_token": "YOUR_REFRESH_TOKEN_1234",
  "scope": "public",
  "created_at": 1486157828
}

Generating A User Authorization Token With Authorization Code Grant Type

A user authorization token is required for endpoints that access user information (e.g. GET /bookings). The password grant flow can generate a token with this level of clearance, however, in some cases an app or a trusted partner may need to access or modify information on behalf of a user when the information needed to use the password grant flow is not available. For this use case, the authorization code grant flow is recommended, that is, acquiring a token with the grant_type parameter set to authorization_code.

In order to use the authorization_code grant flow, the requester first must obtain a code from the oauth/authorize endpoint. The requests query or body parameters must contain an Arrive-issued client_id and client_secret, response_type=code, the client's redirect_uri, a scope (e.g. scope=partner) and either a customer_email or customer_id to identify the customer for whom authorization is being requested. The client_id and client_secret values can also be provided via an Authorization: HTTP Basic Auth header.

For example:

POST /oauth/authorize?response_type=code&customer_email=dev@arrive.com&redirect_uri=http://yoursite.com/oauth/auth_code&client_id=ASSIGNED_CLIENT_ID&client_secret=ASSIGNED_CLIENT_SECRET&scope=partner

On successful acquisition of the authorization code, the client will be redirected to the specified redirect_uri, with the authorization code specified by the code query parameter. This authorization code is valid for 30 minutes.

The user authorization token can then be acquired by posting to /oauth/token with the query or body parameters grant_type=authorization_code, the client redirect as redirect_uri, and the previously acquired authorization code as code. The Arrive-issued client_id and client_secret must be specified as query parameters, body parameters, or in an Authorization: HTTP Basic Auth header.

An example token request using the authorization code:

POST /oauth/token?grant_type=authorization_code&client_id=ASSIGNED_CLIENT_ID&client_secret=ASSIGNED_CLIENT_SECRET&code=AN_AUTHORIZATION_CODE_1234&redirect_uri=https://api.parkwhiz.com/v3/oauth/auth_code&scope=internal

which will yield the response:

{
  "access_token": "YOUR_ACCESS_TOKEN_1234",
  "token_type": "bearer",
  "expires_in": 31557600,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "internal",
  "created_at": 1486404380
}

On successful token generation, you will be supplied with your new access_token, the token_type (bearer), scope of the token's permissions for the requested user, token creation time (created_at) as UNIX timestamp, and number of seconds until token expiration (expires_in). The default expiration time is 1 year.

Use of this token via Authorization: Bearer OAUTH_TOKEN will uniquely and securely identify the user account that was specified in the customer_email or customer_id field in the /oauth/authorize request. So, for example, a request GET /accounts/me will yield a response object of the user specified with customer_email or customer_id.

Refresh Token Grant Flow

The refresh token grant flow can be used to renew tokens before they expire without having to redo the flow used to originally acquire the token. For example, the authorization code grant flow yields a refresh_token as part of its response upon success. To regenerate a new token with the same permissions using the refresh token:

POST /oauth/token?grant_type=refresh_token&client_id=ASSIGNED_CLIENT_ID&client_secret=ASSIGNED_CLIENT_SECRET&refresh_token=YOUR_REFRESH_TOKEN

The request will return a new access_token and a new refresh_token which can be used to regenerate another token using the refresh token grant flow.

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 31557600,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "internal",
  "created_at": 1486409329
}

Note that the refresh token grant flow cannot be used to refresh a token generated from the client credentials grant flow.

None

Many of the endpoints in the Arrive API may be used without authenticating. In general, resources are public if they are not related to a specific account and do not require a scope. Using the API without a token is useful for experimentation. Your rate limit will be significantly lower, and endpoints requiring authorization will return a 401.

If you are giving the API more than a cursory glance, consider using Client Credentials OAuth Token instead.

Scopes

Scopes provide an additional level of control to restrict access to specific resources for access tokens. Using scopes lets you request a token allowing you full access to your user data: scope=partner for use on your servers and restrict access granted to public tokens by using scope=public.

Scopes are also used to verify a request has sufficient permission to access a requested resource. Requests attempting to access data restricted by the data license must have the data scope attached to them.

The scope parameter defines what resources the returned authorization token will have access to. Currently the following scopes are supported: internal, mobile, partner and public where public is the default scope if no value is provided. Scopes will have different api resources they can or cannot access. To determine whether a scope has access to a particular endpoint check the endpoints section.

Some partners may only have the partner and public scopes available to them. If they request a scope that is not granted to them, they will receive an error message.

To declare a scope, add as a parameter to the POST /oauth/authorize or the POST /oauth/token request. Example:

POST /oauth/token?grant_type=client_credentials&client_id=1234abcde&client_secret=abcd1234&scope=internal

will return:

{
  "access_token": "new_token_12345",
  "token_type": "bearer",
  "expires_in": 31557600,
  "scope": "internal",
  "created_at": 1486143527
}```

...
More than one scope can be requested when requesting an access token by separating the requested scopes with spaces.

`Request:`
```http
POST /oauth/token?grant_type=client_credentials&client_id=ASSIGNED_CLIENT_ID_1234&client_secret=ASSIGNED_CLIENT_SECRET_1234&scope=partner public

Response:

{
    "access_token": "88e2c51afc22e71c0da6d5bf29c77d7138fb40c46460c8fa94013cdfff24b974",
    "token_type": "bearer",
    "expires_in": 31557600,
    "refresh_token": "c03c4d7c860dbfc980f43b5bbc0f38bbe27a4d3bf4732bfe919efcbf2bc0ca65",
    "scope": "partner public",
    "created_at": 1499801066
}

If an invalid scope, or a scope that you do not have access to, has been requested you will receive an error.

Request:

POST /oauth/token?grant_type=client_credentials&client_id=ASSIGNED_CLIENT_ID_1234&client_secret=ASSIGNED_CLIENT_SECRET_1234&scope=everything public

Response:

{
    "error": "invalid_scope",
    "error_description": "The requested scope is invalid, unknown, or malformed."
}

Sorting

Available sortable params are documented per endpoint. You can sort by a parameter by specifying the parameter and including which way you would like to sort,asc or desc. For example, you can sort venues by distance, closest first, with this parameter:

?sort=distance:asc

We try to supply sane defaults so you don't have to include asc or desc everywhere. For example, sorting by only name will sort from a-z by default. Sorting by distance will return the closest results first. It would look like this:

?sort=name

Multiple sorting parameters can be supplied and separated with with spaces. It will look similar to:

?sort=name:desc distance

which will sort by name in descending order, followed by distance in ascending order.

Stats

As a utility, the API provides a stats parameter that can perform simple calculations on the results returned by the endpoint calls. For now, the only stat available is count.

To get the count of the number of objects returned from an api call, use result_format=stats&fields=stats:count. For example, to get the number of venues near Chicago, perform:

POST /venues?&q=coordinates:41.881943,-87.630976&result_format=stats&fields=count

which would return a response like:

{
  "count": 5903
}

The count should return the total number of objects returned by the database and pagination will not affect the results.

Searching

A common pattern used on several endpoints allows you to search by one of several types. These types are typically mutually exclusive. When retrieving price quotes for example, you can specify your destination with a variety of search types such as a geographic coordinate, a venue ID, an event ID or a set of geographic bounds.

These searches take a query string parameter q, which is formatted as a space-separated list of query types and values. It will look similar to:

?q=coordinates:41.878,-87.626 distance:5

In the above example, you are querying within 5 miles of downtown Chicago. Keep in mind that the query string is space-separated.

Pagination

By default, you will receive up to 100 results from endpoints that return lists. You may request fewer or step through pages of results using the per_page and page parameters. For example, per_page=10&page=3 indicates you would like records 21-30.

You may only request up to 100 results and requests for more will be capped.

As described in RFC 5988, a Link header field will help in paging through results. It will look similar to this:

Link: <https://api.parkwhiz.com/v4/bookings?page=3&per_page=10>; rel="next", <https://api.parkwhiz.com/v4/bookings?page=2&per_page=10>; rel="prev" <https://api.parkwhiz.com/v4/bookings?page=7&per_page=10>; rel="last"

The "_links" field of response bodies may also have "next" and "prev" links.

The following headers will be returned when paging is occurring:

Header Description
X-Pagination-Per-Page The maximum number of records being returned per page
X-Pagination-Total The total number of records
X-Pagination-Returned The number of records returned for this request
X-Pagination-Current-Page The current page
X-Pagination-Total-Pages The number of pages in the result set when using the given per page limit

Including or Limiting Fields

To keep the response payload to a minimum you can supply a fields parameter specifying only those fields that you wish to receive. The fields should be specified as a comma-separated list.

For example, to retrieve only the ID and geographic coordinates of a parking location, you might use something like this:

GET /v4/locations/2504?fields=id,entrances

You can also retrieve all of the default fields with :default, in addition to any others you specify. This is useful if you need a response field that is rarely used and not returned by default.

GET /v4/locations/2504?fields=:default,rating_summary

Namespacing fields

Fields can be namespaced to the object that they are referencing. The syntax for this is fields=object_name:field_name or fields=object_name::field_group_name for grouped fields. For example, getting the default fields and the rating summary on the location model can be done via namespacing the desired fields:

GET /v4/locations/2504?fields=location::default,location:rating_summary

It is recommended to use namespacing whenever possible, particularly because namespacing is required when requesting fields on linked resources

Grouped vs singular fields

The fields parameter may accept fields that return only one attribute on a resource. For example, fields=event:site_url will cause only the site_url attribute on the event model to be shown. Other fields may cause multiple attributes on a group to be returned. For example, fields=location::address will show the attributes: address1, address2, city, state, postal_code, and country on the location object. By convention fields that yield a singular attribute use a single colon fields=object_name:field_name while grouped attributes use a double colon between the resource and the field group name fields=object_name::field_group_name.

Zooms

Zooms provide an easy way for a single request to return multiple related resources. Normally when requesting a resource additional API calls would be needed to fetch related resources as they are exposed in the _links field. For example, when searching for parking for an event API calls would be needed to retrieve both the event information and the associated venue information. By using zooms, all of this data can be retrieved in a single request and will immediately be available to the API consumer.

As described in JSON Hypertext Application Language (Draft 7), related resources are linked in the "_links" field.

{
    "id": 2504,
    "name": "120 N LaSalle Garage",
    "reviews": { "href": "/locations/2504/reviews" },
    ...
    "_links": {
        "curies": [{ "name": "pw", "href": "https://api.parkwhiz.com/v4/doc/{rel}", "templated": true }],
        "self": { "href": "/locations/2504" },
        "pw:reviews": { "href": "/locations/2504/reviews" }
    }
}

Related resources may be retrieved by using the zoom parameter to cut down on the number of API calls needed. You may use a comma-separated list to request multiple resources.

For example, GET /events/31727?zoom=pw:venue will retrieve the details for event with id: 31727. The Venue the event is hosted at will be contained within the _embedded field.

{
  "id": 31727,
  "name": "Anything Goes",
  "venue_id": 382,
  "start_time": "2011-04-29T19:00:00.000-04:00",
  "end_time": "2011-04-29T22:00:00.000-04:00",
  "_embedded": {
    "pw:venue": {
      "id": 382,
      "name": "Stephen Sondheim Theatre",
      "address1": "124 West 43rd St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10036",
      "_links": {
        "self": {
          "href": "/venues/382"
        },
        "pw:events": {
          "href": "/venues/382/events"
        },
        "pw:quotes": {
          "href": "/quotes?q=venue_id:382"
        },
        "curies": [
          {
            "name": "pw",
            "href": "https://api.parkwhiz.com/v4/{rel}",
            "templated": true
          }
        ]
      }
    }
  },
  "_links": {
    "self": {
      "href": "/events/31727"
    },
    "pw:venue": {
      "href": "/venues/382"
    },
    "pw:quotes": {
      "href": "/quotes?q=event_id:31727"
    },
    "curies": [
      {
        "name": "pw",
        "href": "http://api.parkwhiz.com/v4/{rel}",
        "templated": true
      }
    ]
  }
}

Many resources have default zoomed resources. If you want to ensure no embedded resources are included in the response, you may set zoom=:none.

Specifying fields on linked resources

The fields included on the linked resources can be specified as described in the including or limiting fields section. The key is to namespace the included parameters for the linked resource using the format fields=object_name:field_name or fields=object_name::field_group_name for grouped fields. Additionally, if display fields are specified for the primary resource, those fields should also be namespaced.

Note that purchase_options, ondemand_options, and non_bookable_options are all consolidated under the options object type when requesting fields.

For example, to show the site url of an event and the timezone for the venue that the event is hosted at use GET /events/31727?zoom=pw:venue&fields=event:site_url,venue:timezone. The response will include timezone for venue and the site_url for the event that is being retrieved.

{
  "site_url": "/stephen-sondheim-theatre-parking/anything-goes-31727/",
  "_embedded": {
    "pw:venue": {
      "timezone": "America/New_York",
      "_links": {
        "self": {
          "href": "/venues/382"
        },
        "pw:events": {
          "href": "/venues/382/events"
        },
        "pw:quotes": {
          "href": "/quotes?q=venue_id:382"
        },
        "curies": [
          {
            "name": "pw",
            "href": "https://api.parkwhiz.com/v4/{rel}",
            "templated": true
          }
        ]
      }
    }
  },
  "_links": {
    "self": {
      "href": "/events/31727"
    },
    "pw:venue": {
      "href": "/venues/382"
    },
    "pw:quotes": {
      "href": "/quotes?q=event_id:31727"
    },
    "curies": [
      {
        "name": "pw",
        "href": "http://api.parkwhiz.com/v4/{rel}",
        "templated": true
      }
    ]
  }
}

Note that the GET /quotes endpoint does not support specifying fields on zoomed resources. Zooms can be applied to any endpoint and will load related data into the _embedded field of the response.

Envelope

If envelope=true is passed in the query string, the response will be embedded in the data attribute of the returned object and additional information will be returned.

For example, it might look something like:

    {
        "status":200,
        "record_count":1,
        "start_timestamp":"2013-12-02T19:31:35.5362308Z",
        "end_timestamp":"2013-12-02T19:31:35.6299946Z",
        "time_taken":0.0937638,
        "data":[{
            "payload" : "here",
        }]
    }

The envelope may also contain information about the original request query. For a parking quote search from 6:30-9:30pm CST on December 28, 2015, given location_id 3939, the envelope may look like:

{
  "status": 200,
  "record_count": 1,
  "start_timestamp": "2015-12-03T16:14:09.819Z",
  "end_timestamp": "2015-12-03T16:14:10.081Z",
  "time_taken": 0.262123,
  "query": {
    "location_id": 3939,
    "start_time": "2015-12-28T12:30:00-06:00",
    "end_time": "2015-12-28T15:30:00-06:00"
  },
  "meta": {
    "start_time": "2015-12-28T12:30:00-06:00",
    "end_time": "2015-12-28T15:30:00-06:00",
    "coordinates": [
      41.888460348494,
      -87.628169593019
    ],
    "count": {
      "transient": 1,
      "event": 0
    }
  },
  "data": (Full quotes payload will be here.)
}

Parking quote searches will also contain meta-information about the results in the envelope, such as the start and end times of parking, the geographical coordinates on which the search is centered (e.g. search coordinates, venue coordinates, or centroid of the search bounding box), and result counts grouped by quote type. For a GET /quotes by coordinate search, the envelope would look like:

    {
        "status":200,
        "record_count":1,
        "start_timestamp":"2013-12-02T19:31:35.5362308Z",
        "end_timestamp":"2013-12-02T19:31:35.6299946Z",
        "time_taken":0.0937638,
        "query": {
          "coordinates": [
            41.860273,
            -87.630049
          ],
          "distance": {
            "miles": 0.5
          },
          "start_time": 2015-12-28T18:30:00-06:00,
          "end_time": 2015-12-28T18:30:00-06:00
        },
        "meta": {
          "start_time": 2015-12-28T18:30:00-06:00,
          "end_time": 2015-12-28T18:30:00-06:00,
          "coordinates": [41.860273,-87.630049],
          "count": {
            "transient": 1,
            "event": 0
          }
        }
        "data":[{
            "payload" : "here",
        }]
    }

Envelope functionality is available on all endpoints.

Errors

Responses to unsuccessful requests will contain an errors array, with each error object detailing what went wrong with the following values:

Value Description
code Error code used to identify the specific cause of the problem (e.g. for debugging), and to allow clients to conditionally respond to specific errors
uuid Unique identifier of the error
status The HTTP status code returned
message This is a brief user-friendly description of the error. This can and should be shown to the user
details optional More details may be provided in this field. This is for debugging and development purposes, and should not be shown to the user, nor should it be programmatically parsed and used
fields optional If the error is related to validation of numerous fields, this will specify which input parameters were invalid

Here is an example of a general error:

{
    [
        "code": "customer_unauthorized_api_key",
        "uuid": "375a87d1-f5e3-441c-9a84-5285eb9f1fb5",
        "status": 403,
        "message": "You are not authorized to view this booking"
    ]
}

This example shows what a form validation error might look like:

{
    [
        "code": "booking_quote_id_missing",
        "uuid": "375a87d1-f5e3-441c-9a84-5285eb9f1fb5",
        "status": 400,
        "message": "A booking requires a valid quote",
        "fields": ["quote_id"]
    ]
}

Dates and Times

Searching

Dates and times should be formatted like the following: 2015-09-01T12:44 as specified in ISO 8601.

The API will infer the intended time zone based on the destination or parking location. If a time zone is specified, it will be ignored.

Responses

Date Time objects in API responses will be formatted like the following: 2015-09-01T12:44:00.000-08:00 as specified in ISO 8601

Formatting Conventions

  • Coordinates lists passed to the API are always ordered as [latitude,longitude].
    • You may omit the brackets for convenience
  • Coordinates returned by the API are always ordered as [latitude,longitude] except where used for GeoJSON notation where they are [longitude,latitude].
  • If your request includes a pretty=true param, the response will be indented for readability

Locales and Translations

Locales can be used to retrieve translated content in our system.

Usage

A locale should be passed in with every request using the following header: X-Language-Locale. Supported locales currently include en-US, en-CA, and fr-CA.

Responses

If the locale is passed in correctly, the API response will return the header: X-Language-Locale with the locale that was sent in the request.

If the locale is valid, and we have translated content for the requested data, we will send back the translated content.

Add-Ons

Add-ons are additional options that can be purchased alongside a parking quote retrieved from a call to GET /quotes.

Add-ons, if present, will be a part of the purchase option. Add-ons can either be required or optional.

If an add-on is required ("required" : true) then one of the options present must be sent along with the request to purchase in order to complete a transaction.

Required add-ons

Currently the only required add-ons are related to vehicle size. This allows parking to be purchased for Standard, Oversize, or Supersize vehicles. Each option in the add_ons collection represents one of these selections as denoted in the name field.

Note: To prevent accidental purchases of Standard parking we do not pre-select any required add-ons and require the add-on id to be explicitly sent alongside the request to book parking if vehicle_size add-ons are present in the purchase option. Not all purchase options will have add-ons.

Each vehicle_size add-on option will have the following:

  • name to indicate the name of the add-on
  • price to indicate the price of the add-on
  • availability to indicate whether this type of parking is available or not
  • items that represent what each option represents at that facility. As different facilities have different definitions of Oversize, and Supersize it's important to verify that the vehicle type you are selecting parking for is in the set of items for the option that you purchase.

The list of items is as follows: coupe, sedan, hatchback, wagon, crossover, minivan, suv, truck/van

In the example below you can see the Standard, Oversize, and Supersize add-ons.

"add_ons": {
    "vehicle_size": {
        "required": true,
        "options": [
            {
                "id": "1fd867a5-eaf5-4b2a-95cb-b38bf44c3dc5",
                "name": "Standard",
                "start_time": "2017-10-26T21:30:00.000-05:00",
                "end_time": "2017-10-27T03:30:00.000-05:00",
                "price": {
                    "USD": "0.00"
                },
                "availability": {
                    "status": "available"
                },
                "items": [
                    "Coupe",
                    "Sedan",
                    "Hatchback"
                ],
                "icon": {
                "position": 0,
                    "sizes": {
                        "original": {
                            "URL": "https://d2uqqhmijd5j2z.cloudfront.net/files/102823/original/sedan.png?1465878137",
                            "width": 500,
                            "height": 500
                        }
                    }
                }
            },
            {
                "id": "301a2acc-aa94-4bf2-8aea-e8b3b80b33a6",
                "name": "Oversize",
                "start_time": "2017-10-26T21:30:00.000-05:00",
                "end_time": "2017-10-27T03:30:00.000-05:00",
                "price": {
                    "USD": "10.00"
                },
                "availability": {
                    "status": "available"
                },
                "icon": {
                    "position": 0,
                    "sizes": {
                        "original": {
                            "URL": "https://d2uqqhmijd5j2z.cloudfront.net/files/102824/original/van.png?1465878137",
                            "width": 500,
                            "height": 500
                        }
                    }
                }
            },
            {
                "id": "608ee199-1652-4902-a7ba-0e432db09872",
                "name": "Supersize",
                "start_time": "2017-10-26T21:30:00.000-05:00",
                "end_time": "2017-10-27T03:30:00.000-05:00",
                "price": {
                    "USD": "20.00"
                },
                "availability": {
                    "status": "available"
                },
                "icon": {
                    "position": 0,
                    "sizes": {
                        "original": {
                            "URL": "https://d2uqqhmijd5j2z.cloudfront.net/files/102825/original/truck.png?1465878137",
                            "width": 500,
                            "height": 500
                        }
                    }
                }
            }
        ]
    },
    ...

General Add-Ons

General add-ons are not required for purchase but are value-add services that can be selected with parking.

Below is an example of an optional add-on for a car wash. Note that it contains the same name, price, and availability fields as required add-ons.

"general": {
    "required": false,
    "options": [
        {
            "id": "0ce16a57-f83f-415f-837a-d7277dd5bee2",
            "name": "Car Wash",
            "description": "Get your car washed while you are parked.  Car washes are done professionally inside of our immaculate garage.",
            "start_time": "2017-10-26T21:30:00.000-05:00",
            "end_time": "2017-10-27T03:30:00.000-05:00",
            "price": {
                "USD": "10.00"
            },
            "availability": {
                "status": "available"
            },
            "icon": {
                "position": 0,
                "sizes": {
                    "original": {
                        "URL": "https://d2uqqhmijd5j2z.cloudfront.net/files/102826/original/addon.png?1465878138",
                        "width": 500,
                        "height": 500
                    }
                }
            }
        }
    ]
}

Purchasing Add-Ons

To purchase any add-on you include its id in both the call to preview and purchase in the add_on_ids field. This is a comma-separated list that can hold all add-ons that you would like to purchase. Note that only add-ons attached to a quote can be purchased.

Preview and Checkout

The following section contains a procedure for obtaining a price preview and booking details prior to checkout. To do this, you should first obtain Authorization Credentials, then obtain a Quote ID.

Get a Price Preview

To purchase a booking, you must first call preview and obtain a final price for the purchase. This preview includes the application of any user credits (if applicable), any manually entered coupons or user-specific coupons assigned to an account if the token used is from a logged in user. Users who are not logged in will not have credits or coupons auto applied. More details on the preview endpoint can be found here.

Request:
POST /v4/bookings/previews/
Authorization: Bearer 158020bea60d04a36c844e55d471f4237d7d45a8130b2f2aa75fbe9d6804ef4a

form-data; name="quote_id"  b475180e-e7aa-42af-a736-f3c8d9ca4aa4

Response:
  {
    "user_credit_amount": {
        "USD": "0.0"
    },
    "quote_price": {
        "USD": "15.0"
    },
    "subtotal": {
        "USD": "15.0"
    },
    "final_price": {
        "USD": "15.0"
    },
    "coupon_amount": {
        "USD": "0.0"
    }
}

This response includes all data necessary to inform the user of any coupons or credits used as well as the price that will be paid. When purchasing a booking, the final price must be added to the request. This price must match what the customer was quoted in preview. If the newly calculated price does not match what is passed, an error will be returned.

Make the Booking

The final price should be supplied to the booking's endpoint along with customer information. The booking response below will include all of the data necessary to show details about the booking. Please note the requested fields. If future access to the booking details are desired without authenticating as the user, an authorization code may be requested by adding the field booking: authorization_code. The booking response will then return an authorization_code which will grant access to view the booking anonymously. If more information is desired about the location or seller, these can be added as zooms to the request.

Request:
POST /v4/bookings/
Authorization: Bearer 158020bea60d04a36c844e55d471f4237d7d45a8130b2f2aa75fbe9d6804ef4a

form-data; name="quote_id"  6385df7a-60c2-46e5-8ed6-1f71f596af1c
form-data; name="final_price"  15.00
form-data; name="customer_email"  jkrohn@test.com
form-data; name="customer_firstname"  Joshua
form-data; name="customer_lastname"  Krohn
form-data; name="invoice" true
form-data; name="send_email_confirmation"  true
form-data; name=”fields” booking::default,booking:parking_pass_web_url,booking:authorization_code

Response:
[
    {
        "id": 82256111,
        "customer_id": 2121421,
        "start_time": "2017-10-01T10:00:00.000-05:00",
        "end_time": "2017-10-02T00:00:00.000-05:00",
        "price_paid": {
            "USD": "15.0"
        },
        "full_price": {
            "USD": "15.0"
        },
        "purchased_at": "2017-08-14T11:00:19.867-04:00",
        "type": "transient_booking",
        "cancellable": true,
        "parking_pass_web_url": "http://sandbox.parkwhiz.com/ticket/82256111?u=a3e897e8",
        "authorization_code": "a3e897e8",
        "_embedded": {
            "pw:location": {
                "_links": {
                    "self": {
                        "href": "/locations/6157"
                    },
                    "pw:reviews": {
                        "href": "/locations/6157/reviews"
                    },
                    "pw:quotes": {
                        "href": "/quotes?q=location_id:6157&start_time=2017-08-14T15:00:19+00:00&end_time=2017-08-14T18:00:19+00:00"
                    },
                    "curies": [
                        {
                            "name": "pw",
                            "href": "https://api.parkwhiz.com/v4/{rel}",
                            "templated": true
                        }
                    ]
                }
            },
            "pw:parking_pass": {
                "id": 82256111,
                "status": "active",
                "start_time": "2017-10-01T10:00:00.000-05:00",
                "end_time": "2017-10-02T00:00: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": true,
                        "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": true,
                        "visible": true
                    },
                    {
                        "name": "Security",
                        "description": "Security",
                        "key": "security",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "RVs Allowed",
                        "description": "RVs allowed",
                        "key": "",
                        "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": "",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Free Shuttle From Venue",
                        "description": "Free shuttle from venue",
                        "key": "",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "Electric Car Charging",
                        "description": "Electric car charging",
                        "key": "vehicle_charging",
                        "enabled": true,
                        "visible": true
                    },
                    {
                        "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": "Mobile Pass",
                        "description": "Mobile pass",
                        "key": "eticket",
                        "enabled": true,
                        "visible": false
                    },
                    {
                        "name": "Price Premium",
                        "description": "Price premium",
                        "key": "",
                        "enabled": false,
                        "visible": false
                    },
                    {
                        "name": "ParkWhiz Perk",
                        "description": "ParkWhiz perk",
                        "key": "",
                        "enabled": false,
                        "visible": false
                    }
                ],
                "seller_id": 652,
                "active": true,
                "disclaimers": "No Re-Entry. Customer Responsible for additional fees upon Early Arrivals/Late Departures in accordance with posted rates. Garage allow 10 min grace Period on Arrival and Departure.",
                "price_paid": {
                    "USD": 15
                },
                "full_price": {
                    "USD": 15
                },
                "validation": {
                    "display_message": "Your validation method is your scan code.",
                    "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": "X82256111",
                        "format": "QR",
                        "qr_error_correction_level": "L"
                    },
                    "display": {
                        "pass_number": "required",
                        "scan_code": "required",
                        "license_plate": "hidden",
                        "full_price": "hidden",
                        "pricing_codes": "hidden",
                        "gate_button": "hidden",
                        "print_instructions": "hidden"
                    }
                },
                "reseller_pass": false,
                "_embedded": {
                    "pw:location": {
                        "_links": {
                            "self": {
                                "href": "/locations/6157"
                            },
                            "pw:reviews": {
                                "href": "/locations/6157/reviews"
                            },
                            "pw:quotes": {
                                "href": "/quotes?q=location_id:6157&start_time=2017-08-14T15:00:20+00:00&end_time=2017-08-14T18:00:20+00:00"
                            },
                            "curies": [
                                {
                                    "name": "pw",
                                    "href": "https://api.parkwhiz.com/v4/{rel}",
                                    "templated": true
                                }
                            ]
                        }
                    },
                    "pw:seller": {
                        "_links": {
                            "curies": [
                                {
                                    "name": "pw",
                                    "href": "https://api.parkwhiz.com/v4/{rel}",
                                    "templated": true
                                }
                            ]
                        }
                    },
                    "pw:partner": {
                        "_links": {
                            "curies": [
                                {
                                    "name": "pw",
                                    "href": "https://api.parkwhiz.com/v4/{rel}",
                                    "templated": true
                                }
                            ]
                        }
                    },
                    "pw:add_ons": []
                }
            },
            "pw:customer": {
                "email": "jkrohn@test.com",
                "first_name": "Joshua",
                "last_name": "Krohn",
                "_links": {}
            },
            "pw:add_ons": []
        },
        "_links": {
            "self": {
                "href": "/bookings/82256111"
            },
            "pw:location": {
                "href": "/locations/6157"
            },
            "curies": [
                {
                    "name": "pw",
                    "href": "https://api.parkwhiz.com/v4/{rel}",
                    "templated": true
                }
            ]
        }
    }

View Booking Details Without Authenticating as the User (parking pass)

Using the Booking ID generated above and the authorization code, make a request to view the booking:

Request:
GET /v4/bookings/82256111?authorization_code=a3e897e8
Authorization: Bearer 158020bea60d04a36c844e55d471f4237d7d45a8130b2f2aa75fbe9d6804ef4a

Response:
   {
    "id": 82256111,
    "customer_id": 2121421,
    "start_time": "2017-10-01T10:00:00.000-05:00",
    "end_time": "2017-10-02T00:00:00.000-05:00",
    "price_paid": {
        "USD": "15.0"
    },
    "full_price": {
        "USD": "15.0"
    },
    "purchased_at": "2017-08-14T11:00:19.867-04:00",
    "type": "transient_booking",
    "cancellable": true,
    "_embedded": {
        "pw:location": {
            "_links": {
                "self": {
                    "href": "/locations/6157"
                },
                "pw:reviews": {
                    "href": "/locations/6157/reviews"
                },
                "pw:quotes": {
                    "href": "/quotes?q=location_id:6157&start_time=2017-08-14T15:15:22+00:00&end_time=2017-08-14T18:15:22+00:00"
                },
                "curies": [
                    {
                        "name": "pw",
                        "href": "https://api.parkwhiz.com/v4/{rel}",
                        "templated": true
                    }
                ]
            }
        },
        "pw:parking_pass": {
            "id": 82256111,
            "status": "active",
            "start_time": "2017-10-01T10:00:00.000-05:00",
            "end_time": "2017-10-02T00:00: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": true,
                    "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": true,
                    "visible": true
                },
                {
                    "name": "Security",
                    "description": "Security",
                    "key": "security",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "RVs Allowed",
                    "description": "RVs allowed",
                    "key": "",
                    "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": "",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Free Shuttle From Venue",
                    "description": "Free shuttle from venue",
                    "key": "",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "Electric Car Charging",
                    "description": "Electric car charging",
                    "key": "vehicle_charging",
                    "enabled": true,
                    "visible": true
                },
                {
                    "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": "Mobile Pass",
                    "description": "Mobile pass",
                    "key": "eticket",
                    "enabled": true,
                    "visible": false
                },
                {
                    "name": "Price Premium",
                    "description": "Price premium",
                    "key": "",
                    "enabled": false,
                    "visible": false
                },
                {
                    "name": "ParkWhiz Perk",
                    "description": "ParkWhiz perk",
                    "key": "",
                    "enabled": false,
                    "visible": false
                }
            ],
            "seller_id": 652,
            "active": true,
            "disclaimers": "No Re-Entry. Customer Responsible for additional fees upon Early Arrivals/Late Departures in accordance with posted rates. Garage allow 10 min grace Period on Arrival and Departure.",
            "price_paid": {
                "USD": 15
            },
            "full_price": {
                "USD": 15
            },
            "validation": {
                "display_message": "Your validation method is your scan code.",
                "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": "X82256111",
                    "format": "QR",
                    "qr_error_correction_level": "L"
                },
                "display": {
                    "pass_number": "required",
                    "scan_code": "required",
                    "license_plate": "hidden",
                    "full_price": "hidden",
                    "pricing_codes": "hidden",
                    "gate_button": "hidden",
                    "print_instructions": "hidden"
                }
            },
            "reseller_pass": false,
            "_embedded": {
                "pw:location": {
                    "_links": {
                        "self": {
                            "href": "/locations/6157"
                        },
                        "pw:reviews": {
                            "href": "/locations/6157/reviews"
                        },
                        "pw:quotes": {
                            "href": "/quotes?q=location_id:6157&start_time=2017-08-14T15:15:22+00:00&end_time=2017-08-14T18:15:22+00:00"
                        },
                        "curies": [
                            {
                                "name": "pw",
                                "href": "https://api.parkwhiz.com/v4/{rel}",
                                "templated": true
                            }
                        ]
                    }
                },
                "pw:seller": {
                    "_links": {
                        "curies": [
                            {
                                "name": "pw",
                                "href": "https://api.parkwhiz.com/v4/{rel}",
                                "templated": true
                            }
                        ]
                    }
                },
                "pw:partner": {
                    "_links": {
                        "curies": [
                            {
                                "name": "pw",
                                "href": "https://api.parkwhiz.com/v4/{rel}",
                                "templated": true
                            }
                        ]
                    }
                },
                "pw:add_ons": []
            }
        },
        "pw:customer": {
            "email": "jkrohn@test.com",
            "first_name": "Joshua",
            "last_name": "Krohn",
            "_links": {}
        },
        "pw:add_ons": []
    },
    "_links": {
        "self": {
            "href": "/bookings/82256111"
        },
        "pw:location": {
            "href": "/locations/6157"
        },
        "curies": [
            {
                "name": "pw",
                "href": "https://api.parkwhiz.com/v4/{rel}",
                "templated": true
            }
        ]
    }
}

Endpoints

Price Quotes and Locations

Arrive provides the ability to search for parking at locations across the world. This API provides information on both the bookable parking spaces you can purchase through the API or the ParkWhiz website and apps, as well as the non-bookable parking locations that can be found using the BestParking website and apps.

Understand that the bookable purchase options and non-bookable rate information will often be different. Bookable inventory often has discounts, may have reduced operating hours, or other restrictions.

Please note that access to non-bookable inventory and drive-up rate information requires a license. Contact us for more details.

Required Scopes

It is required to use an authorization header when hitting the quotes endpoints. These endpoints are accessible via tokens with the scope internal, mobile, partner, or public. See the scopes section for more information.

Search for parking price and availability

GET /quotes

Retrieve a list of quotes.

Request
Parameter Type Description
q String required The query for the destination near which you require parking. See above for how to use this parameter.
start_time ISO 8601 Timestamp required for non-event searches The date and time to start parking. If searching for an event, this will default to the event time.
end_time ISO 8601 Timestamp required for non-event searches The date and time to end parking.
mobile_only Boolean This is a deprecated field. Use returns Will return only facilities that are mobile enabled. Default false.
include_sold_out Boolean This is a deprecated field. Use returns Will return sold out locations as well as purchasable locations. Default true.
option_types String bookable (default), non_bookable, or on_demand as a space-separated list. This determines whether the endpoint returns bookable quotes that can be purchased from ParkWhiz, non-bookable drive-up rate information, or both.
returns Return One or more items from the returns collection. If no returns are requested and no booleans are passed in offstreet_bookable will be used.
capabilities Capabilities A set of key:value capabilities separated by spaces as defined in the Capability table. These are additive to the items included by returns.
recommendations_only Boolean Will omit the full data payload and return the recommendations data set only.
external_id String A unique ID generated by the partner to be used in conjunction with the partner to identify a user.
pricing_access_codes String A comma-separated list of pricing access codes. Providing these codes will allow your query to return restricted inventory.

Note: pagination is not supported on this endpoint.

Query Parameters

There are numerous sub-parameters for the q parameter. For some sub-parameters, you can also include distance, which will return quotes within that distance. If not supplied, distance is set to 0.5 miles. Available sub-parameters are as follows:

Query type Description
event_id A ParkWhiz Event ID.
venue_id A ParkWhiz Venue ID.
location_id A ParkWhiz Location ID.
stubhub_venue_id A Stubhub Venue ID
ticketmaster_venue_id A Ticketmaster Venue ID
seller_id One or more ParkWhiz Seller IDs separated by commas.
coordinates A set of coordinates. See the note on coordinates
bounds A comma-separated list of coordinates. They must be sequential clockwise, though you can start with any coordinate and bounds can be any polygon. See the note on coordinates
distance The radius around a pair of coordinates, event, or venue. This is measured in miles and defaults to 0.5.
search_type Specify the type of parking to search for (transient, monthly, event_package). A default search will be for transient parking.
anchor_coordinates A set of coordinates. This will server as the anchor for distance calculation. See the note on coordinates
event_package_id A ParkWhiz Event Package ID.
partner_event_id A Partner's event ID. This must be used in combination with event_source_partner_id.
event_source_partner_id An Event Source Partner ID. See below for valid Event Source Partners.
pricing_access_code_exclusive When true, only return quotes that require one of the supplied pricing_access_codes. See pricing_access_codes under the Request section for more information.
ticketmaster_event_id deprecated Use partner_event_id with event_source_partner_id:1 instead of this param.

Note: Search areas larger than 50 square miles are not supported. If your search exceeds this size you will receive an error response indicating the requested area is too large.

Event Source Partners

Below is the complete list of partners whose event IDs are supported in the partner_event_id field. To query by a partner_event_id, you must also supply the event_source_partner_id listed below.

Event Source Partner event_source_partner_id
AXS 75
Ticketmaster 1

Returns

Returns help to filter out undesired results and ensure that all content returned is relevant to the client requesting the search. Returns are additive to the result set and their order does not matter. More returns will be added as new data types are introduced to the API.

Returns Properties
offstreet Offstreet inventory. Include bookable, non-bookable, and sold out
offstreet_bookable Offstreet, bookable inventory
offstreet_bookable_mobile Offstreet bookable inventory that is only mobile enabled
offstreet_bookable_sold_out Offstreet bookable inventory that is currently unavailable due to being sold out
offstreet_non_bookable Offstreet, non-bookable inventory
suggested_view A set of items suggested by the API to show on the map. If no items are found one or more of nearby_metros or nearby_venues may be included.
onstreet Returns on street parking options
recommendations Returns a set of recommended near the destination using both on street and offstreet data. Recommendations are comprised of the results requested in other returns.

Capabilities

Capabilities provide search results with specific purchase or pre-purchase restrictions, denoted by a set of Key:Value pairs.

Key Values Notes
capture_plate always, post, never If always, items that require a license plate to complete a purchase may be returned. post indicates an ability to collect a license plate after a purchase. never indicates that this client cannot capture license plates and these options should not be presented. If not included it will be assumed that at a minimum the client can use the web version of the pass with the authorization code to allow the customer to enter a license plate.
booking_validation_via_on_demand ble_inugo_v2 Sending in ble_inugo_v2 signifies that the client can support the booking validation via on demand flow for ble_inugo_v2.
Sample Searches

Coordinate Example

https://api.parkwhiz.com/v4/quotes/?q=coordinates:41.881943,-87.630976&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable

Bounds Example

https://api.parkwhiz.com/v4/quotes/?q=bounds:[[41.881943,-87.630976],[41.882071,-87.626191],[41.878205,-87.626148],[41.878301,-87.633680]]&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable

For convenience, you may omit the brackets. e.g.

https://api.parkwhiz.com/v4/quotes/?q=bounds:41.881943,-87.630976,41.882071,-87.626191,41.878205,-87.626148,41.878301,-87.633680&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable

Coordinates, only mobile enabled

https://api.parkwhiz.com/v4/quotes/?q=coordinates:41.881943,-87.630976&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable_mobile

Coordinates, bookable and non bookable data

https://api.parkwhiz.com/v4/quotes/?q=coordinates:41.881943,-87.630976&start_time=2015-11-22T16:35:28-06:00&end_time=2015-11-22T19:35:44-06:00&returns=offstreet_bookable offstreet_non_bookable
Response

The response will be an array of Quote models.

Recommendations: When requesting recommendations there is an additional recommendations object that has the following information

Field Type Description
meta Meta Object Contains meta data about the recommendation response
meta[statements] Statements A collection of statements about known parking attributes of the city in which the parking search was performed
meta[probabilities] Probabilities Object Contains probability and confidence information related to recommendations
probabilities[offstreet] Probability
probabilities[onstreet] Probability
data Array[Recommendation] An ordered list of recommendations

Envelope: When requesting the envelope there is an additional meta object that has the following information:

Field Type Description
start_time ISO 8601 Timestamp The start time that you passed to GET /quotes.
end_time ISO 8601 Timestamp The end time that you passed to GET /quotes.
coordinates Array[Coordinates] The coordinates of the center of your search.
count Object A count of the different types of quotes returned, with keys transient, event, monthly, unavailable. E.g. {"transient":71,"event":0,"monthly":0,"unavailable":1}
Error responses
Status Message
404 No quotes found
400 This will supply a field and relevant validation error message (e.g. {"field": "query_type", "message": "Query type is required"})

The following resources can be retrieved with the zoom parameter as described in the section on linking

Field Description
pw:location A location model

Note that this endpoint does not support specifying fields on nested resources.

Quotes Playground
Run Clear /v4/quotes/
Run the query to see a response.

Search for parking facilities in a geographic area.

GET /locations

Authentication

All requests must include a bearer token.

Request
Parameter Type Description
q String required The query for the destination near which you require parking. See above for how to use this parameter.

Note: pagination is not supported on this endpoint.

There are numerous sub-parameters for the q parameter. For some sub-parameters, you can also include distance, which will return quotes within that distance. If not supplied, distance is set to 0.5 miles. Available sub-parameters are as follows:

Query type Description
venue_id A ParkWhiz Venue ID.
coordinates A set of coordinates. See the note on coordinates
bounds A comma-separated list of coordinates, provided either as a series of coordinate lists or as a one-dimensional array of lat/long data. They must be sequential clockwise, though you can start with any coordinate and bounds can be any polygon.
distance The radius around a pair of coordinates, event, venue, or gplaces_place. This is measured in miles and defaults to 0.5.
beacon A string identifying a physical beacon associated with a location.
Response

The response will be an array of Location models.

Locations Playground
Run Clear /v4/locations/
Run the query to see a response.

Retrieve single facility

GET /locations/{location_id}

Retrieve details about the specified parking facility.

Request
Parameter Type Description
location_id String required ParkWhiz Location ID
Response

The response will be a location model.

Error responses
Status Message
404 Location not found
400 This will supply a field and relevant validation error message

Create facility review

POST /locations/{location_id}/reviews

Create a review for the specified facility.

Request
Parameter Type Description
booking_id Integer required ParkWhiz Location ID
rating Integer required The user's rating of the location, from 1-5.
comment String The comment left by the user about the location.
Response

The response will be a location model.

Retrieve facility reviews

GET /locations/{location_id}/reviews

Retrieve reviews for specified parking facility.

Request
Parameter Type Description
location_id String required ParkWhiz Location ID
Response

The response will be an array of review models.

Error responses
Status Message
404 No reviews found
400 This will supply a field and relevant validation error message (e.g. {"field": "location_id", "message": "Location ID is required"})

Retrieve single review

GET /locations/{location_id}/reviews/{review_id}

Retrieve a specific parking facility review.

Request
Parameter Type Description
location_id Integer required ParkWhiz Location ID
review_id Integer required ParkWhiz Review ID
Response

The response will be a review model.

Error responses
Status Message
404 Review not found
400 This will supply a field and relevant validation error message (e.g. {"field": "review_id", "message": "Review ID must be an integer"})

Bookings

The following endpoints allow you to create and manage your parking bookings. These will return a 401 status if you are not authenticated.

Note: If you are providing access control solutions for a parking location and need a list of upcoming bookings, contact dev-admin@arrive.com for a different Access Control API. These are only for managing and viewing your own, personal parking.

Required Scopes

The bookings endpoints are accessible via tokens with the scope internal, mobile, partner, or public. See the scopes section for more information.

Book parking

POST /bookings

Book parking based on a quote.

Authentication

Either a client credentials or user authorization OAuth token of the target account is required.

Request

Booking parameters should be provided in the POST body.

Parameter Type Description
final_price Float required Purchase price returned by POST /bookings/previews
quote_id String ParkWhiz Purchase Option ID (supplied by GET /quotes, resembling a UUID)
booking_hold_id Integer ParkWhiz Partner Booking Hold ID
add_on_ids String Comma-separated list of ParkWhiz Add On IDs to purchase with this quote (supplied by GET /quotes, resembling a UUID)
customer_id Integer ParkWhiz ID of the customer that the quote is being purchased for
customer_email String Email of the customer that the quote is being purchased for
customer_first_name String First name of the customer that the quote is being purchased for
customer_last_name String Last name of the customer that the quote is being purchased for
payment_method_nonce String One-time use Braintree payment nonce generated by the client
saved_payment_token String BT token of previously saved payment method
save_credit_card Boolean Whether the customer wants their credit card saved for future use
skip_credit_card_vaulting Boolean Should the credit card vaulting in Braintree be skipped
enterprise_account_id Integer ID of the Enterprise account being used to pay for this purchase
expense_memo String Note attached to this purchase when made through Enterprise
invoice Boolean Whether to book parking for a partner on invoice
coupon_code String ParkWhiz coupon code
auto_apply_coupon Boolean Whether to automatically apply ParkWhiz coupons attached to the customer
device_data String Braintree/Kount device data for fraud prevention
partner_booking_id String The requesting partner's external ID attributed to this purchase. Links the partner order to the Arrive booking.
portal_affiliate_id Integer ID of the Portal affiliate account to be credited for this purchase
legacy_affiliate_id Integer ID of the legacy affiliate account to be credited for this purchase
monthly_start_date ISO 8601 Timestamp Date on which the customer's monthly parking begins
send_email_confirmation Boolean Whether to send a ParkWhiz booking confirmation email to the customer (default false)
plate_number String If sent in this will add a license plate to the booking.
vehicle_id Integer If sent in this will add the license plate of the vehicle that corresponds to the vehicle_id.
marketing_allowed Boolean Whether to allow ParkWhiz marketing content to be sent to the user (only applies to new users created through checkout), defaults to false
purchase_vector String deprecated Information about how the customer accessed and purchased parking

Either the quote_id or booking_hold_id MUST be provided.

Either the customer_id or customer_email must be provided for purposes of customer identification.

Response

The response will be an array of booking model objects.

Error responses
Status Message
404 Location not found
400 This will supply a field and relevant validation error message (e.g. {"field": "location_id", "message": "Location ID must be an integer"})

Preview booked parking

POST /bookings/previews

Preview the booking resulting from purchase of a parking quote.

Authentication

Either a client credentials or user authorization OAuth token of the target account is required.

Request

Booking parameters should be provided in the POST body.

Parameter Type Description
quote_id String required ParkWhiz Purchase Option ID (supplied by GET /quotes, resembling a UUID)
auto_apply_coupon Boolean Whether to automatically apply ParkWhiz coupons attached to the customer
add_on_ids String Comma-separated list of ParkWhiz Add On IDs to purchase with this quote (supplied by GET /quotes, resembling a UUID)
book_extended_times Boolean Whether to book auto-extended start and end times (true) or those from the original search (false)
coupon_code String ParkWhiz coupon code
create_distinct_hold Boolean booking hold param Create a new booking hold even if a booking hold already exists
hold_expires_in Integer booking hold param Time in seconds after which the booking hold will expire
purchase_vector String Information about how the customer accessed and purchased parking
validate_add_ons Boolean Whether to validate the add ons or not

If this endpoint is called with a token that is associated with a partner that has opted in to booking holds, then a booking hold will be created. Details about this booking hold can be retrieved using the zoom: "pw:booking_hold" (see the section on zooms) parameter.

If you pass in the create_distinct_hold parameter, then the supplied quote_id can no longer be used to call POST /bookings to checkout with this booking hold, or any other booking hold made with this same quote_id. To checkout with this booking hold, you must store the booking hold ID obtained from this response (in the pw:booking_hold zoom) and then use it as the booking_hold_id parameter in the call to POST /bookings.

Response

The response will be a booking preview model.

Error responses
Status Message
400 This will supply a relevant error code and error message (e.g. {"code": "error_code", "message": "Human readable error message"})
403 The requesting partner does not have permission to create booking holds, but supplied a booking hold param to the request
404 The requested quote_id has expired

Retrieve booking list

GET /bookings

Retrieve a list of bookings that have been purchased under your account, or that another user has shared with you.

Authentication

A user authorization OAuth token of the target account is required.

Request
Parameter Type Description
q See below The query for your bookings search. See above for how to use this parameter.
share_filter See below

There are numerous sub-parameters for the q parameter. Available sub-parameters are as follows:

Query types Description
starting_after A timestamp, limiting returned bookings to those starting after this time
starting_before A timestamp, limiting returned bookings to those starting before this time
upcoming A shortcut to specifying starting_after with the current date and time. Activated with value true
past A shortcut to specifying starting_before with the current date and time. Activated with value true
active A shortcut specifying that you want bookings that have not been cancelled or refunded. Active passes may be in the past or upcoming.
cancelled A shortcut specifying that you want bookings that have been cancelled or refunded
busines_purchase A shortcut specifying that you want bookings purchased with a Business Profile or ParkWhiz for Business account
location_id The ID(s) of a ParkWhiz location, limiting bookings to those facilities e.g. 1234,5678
license_plate A list of license plates, limiting bookings to those with the following license plates e.g. ABC123,ZYX987. Also can be activated by the value true, limiting bookings to those with any license plates.
on_demand A shortcut specifying that you want on demand bookings. Must specify false if they should not be included.
shared_by_authenticated_user Return bookings that have or have not been shared by the authenticated user. When true, return only bookings that have been shared by the authenticated user. When false, return only bookings that have not been shared by the authenticated user. A booking that has been shared and then revoked is considered unshared.

This endpoint allows a user to view all bookings that they have purchased and that have ever been shared with them, even if they then shared that booking with another user (see below for more context on booking sharing). The share_filter parameter allows the user to limit what bookings are returned based on the user's position in the current chain of booking shares. You can pass in multiple filter types and the endpoint will return all bookings that fit any one type you pass in.

Filter type Description
original_purchaser This returns bookings you yourself purchased, even if you've then shared them with someone else.
intermediate_transferer This returns bookings that have been shared with you, that you have shared with someone else, and that person has then shared the booking again.
most_recent_transferer This returns bookings that have been shared with you that have then been shared with someone else, and that person has not shared the booking with anyone else yet.
most_recent_transferee This returns bookings that have been shared with you, and that you have not shared with anyone else.

As an example, if a booking was purchased by User A, who shares it with User B, who shares it with User C, who shares it with User D, who finally shares it with User E who keeps it for themself, this is what the chain would look like and what parameter each User would need to pass in to get the booking returned.

User Filter type
User A original_purchaser
User B intermediate_transferer
User C intermediate_transferer
User D most_recent_transferer
User E most_recent_transferee

If share_filter is not defined, this endpoint will default to original_purchaser,most_recent_transferee. So, in the example above, Users A and E would get the booking returned to them without having to pass in a sharer_filter value, and Users B, C and D would not.

Response

The response will be an array of booking models.

Error responses
Status Message
400 This will only happen if you don't send any valid parameters, e.g. {"fields": ["starting_after", "starting_before", "account_id", "past", "upcoming"], "message": "At least one parameter is required"}
403 You do not have permission to retrieve these bookings (e.g. not having access to the account you provided with account_id)
404 No bookings found

Retrieve booking details

GET /bookings/{booking_id}

Get details of a booking

Authentication

In order to receive data back for a booking or booking hold, you must supply one of the following:

  • The booking authorization_code
  • An active share code created by the owner of the booking (see below)
  • A partner client credentials OAuth Bearer Token for the partner attributed with the booking
  • A user authorization OAuth Bearer Token for the user whose bookings you are accessing
    • NOTE: If you are looking up a booking hold, the user authorization token must be the same token that was used to create the booking hold
Request
Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID or Partner Booking Hold ID
authorization_code String One click authorization code for the ParkWhiz booking, or a share code for the booking

If a Partner Booking Hold ID is supplied in place of a Booking ID, then a booking hold will be returned.

Response

The response will be a booking model

Error responses
Status Message
400 This will supply a field and relevant validation error, e.g. {"field": "booking_id", "message": "Booking ID must be an integer"}
404 Booking was not found
403 This booking share has been revoked.
403 This booking has been given to another user. Revoke that share before accessing booking.

Cancel booking

DELETE /bookings/{booking_id}

Cancel a booking.

Authentication

Either a client credentials token or user authorization OAuth token of the target account is required. Alternatively, you can pass the booking's authorization_code as a parameter.

Request
Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID or Partner Booking Hold ID
send_email_confirmation Boolean Whether or not you would like ParkWhiz to send an email confirmation to the customer
authorization_code String One click authorization code for the ParkWhiz booking

If a Partner Booking Hold ID is passed in instead of a Booking ID, then the booking hold will be deleted. Deleting a booking hold requires the booking hold authorization code, an internal token, the partner's token, or the user token that was used to create the booking hold.

Response

The response will be a 204 (No Content) HTTP status.

Error responses
Status Message
400 Past bookings cannot be cancelled
403 Not authorized to cancel this booking
404 Booking not found

Retrieve booking parking pass

GET /bookings/{booking_id}/parking_passes

Get a pre-formatted ParkWhiz parking pass for this booking. The parking pass will be the only element of a length 1 array.

Authentication

A user authorization OAuth token for the account holding the booking is required.

Request
Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID
Response

The response will be an array of parking pass models containing one element.

Error responses
Status Message
400 This will supply a field and relevant validation error, e.g. {"field": "booking_id", "message": "Booking ID must be an integer"}
404 Booking was not found

Retrieve vehicle associated with this booking

GET /bookings/{booking_id}/vehicles

Get information about the vehicle associated with a booking. This is used to validate a vehicle at many parking locations.

Authentication

A user authorization OAuth token of the target account is required.

Request
Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID
Response

The response will be an array of vehicle models containing one element.

Error responses
Status Message
400 This will supply a field and relevant validation error, e.g. {"field": "booking_id", "message": "Booking ID must be an integer"}
404 Booking was not found

Set the vehicle associated with this booking

PUT /bookings/{booking_id}/vehicles

Add information about the vehicle associated with a booking. This is used to validate a vehicle at many parking locations.

Authentication

A user authorization OAuth token of the target account is required.

Request
Parameter Type Description
booking_id Integer required A ParkWhiz Booking ID
vehicle_id Integer A ParkWhiz vehicle ID
plate_number String A vehicle license plate number
plate_state String A vehicle license plate state
label String A descriptive label for the vehicle
default Boolean Whether this is the customer's default vehicle
booking_authorization_code String When this is set, a new vehicle will be created to be associated with this booking. This new vehicle will not be set as the default vehicle for the user.

A known and existing vehicle can be attached to the booking by specifying a vehicle_id. If the desired vehicle does not exist in the ParkWhiz system, the plate_number and plate_state must be specified to add a new vehicle, with label and default optional.

Response

The response will be a vehicle model.

Error responses
Status Message
400 This will supply a field and relevant validation error, e.g. {"field": "booking_id", "message": "Booking ID must be an integer"}
404 Booking was not found

Preview extended booking parking

POST /bookings/{booking_id}/previews

Quote and preview the result of modifying the time of an existing booking.

Authentication

Either a client credentials token or user authorization OAuth token of the target account is required. Alternatively, you can pass the booking's authorization_code as a parameter.

Request

Preview parameters should be provided in the POST body.

Parameter Type Description
authorization_code String One click authorization code for the ParkWhiz booking
end_time ISO 8601 Timestamp The new parking end time
include_suggestions Boolean Whether or not to return up to 3 suggested new parking times. Defaults to false

Currently you can only use this endpoint AFTER the booking has started. If an end_time parameter is not provided, you must specify include_suggestions=true.

Response

The response will be a booking extend preview model.

Error responses
Status Message
400 Booking was already cancelled
400 End time was in an invalid format
400 Location does not support booking extension
400 Modifying a booking (before the start time) is not yet supported
400 New end_time must be greater than booking's current end time
401 You are not authorized for this booking
404 Booking not found
500 Resources required to complete this request are currently not available

Book extended parking

PUT /bookings/{booking_id}

Extend the time of an existing booking given a quote id obtained from the extend preview endpoint.

Authentication

Either a client credentials token or user authorization OAuth token of the target account is required. Alternatively, you can pass the booking's authorization_code as a parameter.

Request
Parameter Type Description
final_price Float required Purchase price returned by POST /bookings/{booking_id/previews
quote_id String required ParkWhiz purchase option id returned by POST /bookings/{booking_id/previews resembling a UUID
authorization_code String One click authorization code for the ParkWhiz booking
device_data String Braintree/Kount device data for fraud prevention
enterprise_account_id Integer ID of the Enterprise account being used to pay for this purchase
expense_memo String Note attached to this purchase when made through Enterprise
invoice Boolean Whether to book parking for a partner on invoice
payment_method_nonce String One time use Braintree payment nonce generated by the client
saved_payment_token String Braintree token of previously saved payment method
send_email_confirmation Boolean Whether to send a ParkWhiz booking confirmation email to the customer (default false)

Currently you can only use this endpoint AFTER the booking has started. At least one of enterprise_account_id, invoice, payment_method_nonce or saved_payment_token must be provided.

Response

The response will be an updated booking model reflecting the changes.

Error responses
Status Message
400 Booking was already cancelled
400 Location does not support booking extension
400 Modifying a booking (before the start time) is not yet supported
400 New end_time must be greater than booking's current end time
400 The requested quote id has expired
401 You are not authorized for this booking
404 Booking not found
500 Resources required to complete this request are currently not available

Get tickets associated with a booking

GET /bookings/{booking_id}/tickets

Retrieve the tickets associated with a booking.

Authentication

In order to receive data back, you must supply one of the following:

Request
Parameter Type Description
booking_id (route_param) Integer required The ParkWhiz Booking ID
authorization_code String The one-click authorization code for the booking
Response

A successful response will include a 200 with an array of ticket models in the body. If there are no tickets associated with the specified booking, an empty array will be returned.

Error responses
Status Code Message
401 unauthorized_for_booking_tickets Not authorized to view this booking's tickets
404 booking_not_found Booking not found

Monthly Bookings

Required Scopes

The monthly bookings endpoints are accessible via tokens with the scope internal, mobile, or public. See the scopes section for more information.

Retrieve monthly booking list

GET /monthly_bookings

Retrieve a list of monthly bookings that have been purchased under your account.

Authentication

A user authorization OAuth token of the target account is required.

Request
Parameter Type Description
q See below The query for your monthly bookings search. See above for how to use this parameter.

Query types Description
starting_after A timestamp, limiting returned monthly bookings to those starting after this time
starting_before A timestamp, limiting returned monthly bookings to those starting before this time
upcoming A shortcut to specifying starting_after with today's date
past A shortcut to specifying starting_before with today's date
active A shortcut specifying that you want monthly bookings that have not been cancelled or refunded
cancelled A shortcut specifying that you want monthly bookings that have been cancelled or refunded
location_id The ID(s) of a ParkWhiz location, limiting monthly bookings to those facilities e.g. 1234,5678
Response

The response will be an array of monthly booking models.

Error responses
Status Message
400 There are no valid fields in your request.
401 Not authorized to view this monthly booking
404 Monthly Booking was not found

Retrieve monthly booking details

GET /monthly_bookings/{monthly_booking_id}

Get details of a monthly booking.

Authentication

A user authorization OAuth token of the target account is required.

Request
Parameter Type Description
monthly_booking_id Integer required A ParkWhiz Monthly Booking ID
authorization_code String One click authorization code for the ParkWhiz booking
Response

The response will be a booking model.

Error responses
Status Message
400 There are no valid fields in your request.
401 Not authorized to view this monthly booking
404 Monthly Booking was not found

Venues and Events

Search venues

GET /venues

Request
Parameter Type Description
q Query String The search query string
sort Sort String The search query string

Query types Type Description
name String Name of your destination venue
coordinates Coordinates The coordinate of your destination
slug String Unique URL identifier for venue
stubhub_venue_id String A StubHub venue ID
ticketmaster_venue_id String A Ticketmaster venue ID
Sort by Description
name The names of the venues
distance Distance to the venue, with respect to the search coordinates (if provided)
Response

The response will be an array of venue models.

Retrieve venue details

GET /venues/{venue_id}

Retrieve details about a specific venue.

Request
Parameter Type Description
venue_id Integer required ParkWhiz Venue ID
Response

The response will be a venue model.

Error responses
Status Message
404 Venue not found
400 This will supply a field and relevant validation error message (e.g. {"field": "venue_id", "message": "Venue ID must be an integer"})

Retrieve events at venue

GET /venues/{venue_id}/events

Retrieve a list of events at a specific venue.

Request
Parameter Type Description
venue_id Integer required ParkWhiz Venue ID
q Query String The search query string
sort Sort String The search query string

Query types Type Description
name String Name of your destination event
starting_before ISO 8601 Timestamp Only return events starting before this time
starting_after ISO 8601 Timestamp Only return events starting after this time. Default: the current time.
Sort by Description
name The names of the events
start_time Start times of the events
Response

The response will be an array of event models.

Search events

GET /events

Retrieve a list of events.

Request
Parameter Type Description
q Query String The search query string
sort Sort String The search query string

Query types Type Description
name String Name of your destination event
starting_before ISO 8601 Timestamp Only return events starting before this time
starting_after ISO 8601 Timestamp Only return events starting after this time
venue_id Integer(s) list of ParkWhiz venue ID(s) to filter events by e.g. 1234,5678
partner_event_id String A Partner's Event ID. This must be used in combination with event_source_partner_id.
event_source_partner_id Integer The source of this external Partner Event ID. See Event Source Partners for valid partners.
Sort by Description
name The names of the events
start_time Start times of the events
Response

The response will be an array of event models.

Retrieve event details

GET /events/{event_id}

Retrieve details about the specified event.

Request
Parameter Type Description
event_id Integer required ParkWhiz Event ID
Response

The response will be a event model.

Error responses
Status Message
404 Event not found
400 This will supply a field and relevant validation error message (e.g. {"field": "event_id", "message": "Event ID must be an integer"})

Hubs

Search hubs

GET /hubs

Retrieve a list of hubs.

Request
Parameter Type Description
q Query String The search query string

Query types Type Description
nearby_coordinates Coordinates Coordinates that are near to the hub
distance Integer the maximum distance between nearby_coordinates and the hubs to be matched. Default 50
only_major_metros Boolean Will only return major metro areas (eg: New York, Chicago, San Francisco, DC)
Response

The response will be an array of hub models.

Accounts

Required Scopes

The accounts/payment_methods endpoints are accessible via tokens with the scope internal, mobile, or public. See the scopes section for more information.

Create new account

POST /accounts

Create a new account.

Request
Parameter Type Description
email String Required The email address that you want to use.
first_name String Required The first name that you want to use.
last_name String Required The last name that you want to use.
password String The password that you want to use.
phone_number Integer The phone number that you want to use.
phone_country_code Integer Phone country code, defaults to 1.
marketing_allowed Boolean Whether to allow ParkWhiz marketing content to be sent to the user, defaults to false.
passwordless Boolean Create the account without a password. When this field is true the password field must not be sent
Response

The response will be an account model.

Errors
Status Message Code
400 (An array of validation errors.)
400 Password must not be sent for passwordless. account_passwordless_with_password

Your account overview

GET /accounts/me

Get your account info. This is an alias for /accounts/{account_id}. "me" may be used in place of the account ID in all accounts endpoints.

Request

There are no additional parameters for this request.

Response

The response will be an account model.

Error responses
Status Message
403 You must be logged in to use this shortcut.

Account overview for user

GET /accounts/{account_id}

Retrieve your account overview.

Request

There are no additional parameters for this request.

Response

The response will be an account model.

Error responses
Status Message
403 You must be logged in to use this shortcut.
404 That account could not be found.

Update account info

PUT /accounts/{account_id}

Update your account information.

Request
Parameter Type Description
email String The email address that you want to use.
password String The password that you want to use.
first_name String The first name that you want to use.
last_name String The last name that you want to use.
phone_number Integer The phone number that you want to use.
marketing_allowed Boolean Whether the user has opted in/out to receive ParkWhiz marketing content.
Response

The response will be an account model.

Errors
Status Message
400 Account could not be updated.
404 You must use 'me' as the ID.

Get a list of your frequent locations

GET /accounts/{account_id}/frequent_locations

Retrieve a list of active locations the customer has booked at more than once, ordered by number and recency of bookings.

Response

The response will be a list of location models.

Errors
Status Message
404 You must use 'me' as the ID.

GET accounts/{account_id}/recommendations

Retrieve a list of recommended booking locations and times, based on the customer's previous purchase history.

Request
Parameter Type Description
limit Integer Maximum number of recommendations to return. Defaults to 5,100 max.
Response

The response will be a list of recommendations ordered by relevancy as follows:

Field Type Description
start_time ISO 8601 Timestamp The recommended start time to book.
end_time ISO 8601 Timestamp The recommended end time to book.
location_id Integer The ParkWhiz location ID of the recommended location.

The following resources can be retrieved with the zoom parameter as described in the section on linking. The location is part of the default zoom.

Field Description
pw:location The quote's location
Errors
Status Message
404 You must use 'me' as the account_id.

Retrieve vehicles

GET /accounts/{account_id}/vehicles

Retrieve a list of vehicles saved to the account.

Request

No additional parameters are required.

Response

The response will be an array of vehicle models.

Errors
Status Message
404 You must use 'me' as the ID.

Add vehicle

POST /accounts/{account_id}/vehicles

Store vehicle information for use in a future booking.

Request
Parameter Type Description
label String Required A brief label for the vehicle. For example, "Bill's SUV".
plate_number String Required The license plate number.
plate_state String The license plate state.
default Boolean Whether or not this vehicle is the account's default vehicle. Note: an account can only have one default vehicle.
Response

The response will be a vehicle model.

Errors
Status Message
404 You must use 'me' as the ID.

Retrieve vehicle details

GET /accounts/{account_id}/vehicles/{vehicle_id}

Retrieve details about a specified vehicle saved to the account.

Request

There are no additional parameters for this request.

Response

The response will be a vehicle model.

Errors
Status Message
404 That vehicle was not found.
404 You must use 'me' as the ID.

Update vehicle details

PUT /accounts/{account_id}/vehicles/{vehicle_id}

Update the specified vehicle saved to the account.

Request
Parameter Type Description
label String A brief label for the vehicle. For example, "Bill's SUV".
plate_number String The license plate number.
plate_state String The license plate state.
default Boolean Whether or not this vehicle is the account's default vehicle. Note: an account can only have one default vehicle.
Response

The response will be a vehicle model.

Remove vehicle

DELETE /accounts/{account_id}/vehicles/{vehicle_id}

Remove the specified vehicle from the account.

Request

There are no additional parameters for this endpoint.

Response

The response will be a Status 204 NO CONTENT code.

Errors
Status Message
400 This vehicle could not be deleted.
404 That vehicle was not found.
404 You must use 'me' as the ID.

Get payment methods associated with the account

GET /accounts/{account_id}/payment_methods

Retrieve a list of payment methods associated with the authenticated account.

Request

There are no additional parameters for this request.

Response

The response will be an array of payment methods.

Errors
Status Message
400 There are no valid fields in your request.
404 You must use 'me' as the ID.

Add payment method to account

POST /accounts/{account_id}/payment_methods

Request
Parameter Type Description
payment_method_nonce String ** Required** Braintree nonce passed in from client
Response

The response will be a payment method.

Errors
Status Message
400 Unable to save payment method
404 You must use 'me' as the ID.

Edit a user's payment method

PUT /accounts/{account_id}/payment_methods/{braintree_token}

Update a personal account's credit card or modify an account's ParkWhiz for Business status.

This endpoint requires a Braintree payment method nonce. To learn more about the Braintree payment method nonce refer to the Braintree documentation.

Request
Parameter Type Description
payment_method_nonce String Required Braintree nonce passed in from client
label String Optional The label for the credit card
is_default Boolean Optional Whether or not the card is the user's default payment method
Response

The response will be a payment method. A successful response will update the model's attributes with the latest values from Braintree.

Errors
Status Code Message
200 n/a Payment method was edited successfully
400 no_valid_fields There are no valid fields in your request.
400 braintree_payment_method_error unable to save payment method
400 update_payment_method_has_active_ticket Can't update a payment method that has an active ticket
401 unauthorized_payment_tokens You must be logged in to use this endpoint
404 payment_method_not_found Payment method not found.

Delete or disable payment methods

DELETE /accounts/{account_id}/payment_methods/{braintree_token}

Delete credit cards from personal accounts and disable enterprise account status from ParkWhiz for Business accounts.

Request

There are no additional parameters for this request.

Response

The response will be a 204 status code.

Errors
Status Code Message
400 del_payment_method_has_active_ticket Can't delete a payment method that has an active ticket
401 unauthorized_payment_tokens You must be logged in to use this endpoint
403 no_enterprise_membership User is not attached to supplied enterprise account.
404 del_payment_methods_id_not_me You must use 'me' as the ID.
404 del_no_method Payment method was not found.

Recover account

POST /accounts/recoveries

Send a recovery email.

Request
Parameter Type Description
email String Required The email address of that account that you are recovering.
Response

The response will be a 202 status code.

Errors
Status Message
400 Sorry, your account's password was not reset.
404 We could not find an account with that email address.

Reset account password

POST /accounts/reset_password

Reset an account's password using the token from their password reset email.

Request
Parameter Type Description
email String Required The email address of that account that you are recovering.
password String Required The new password for the account.
password_reset_token String Required The reset token provided in the password reset email.
client_id String The client id for the oauth application, ParkWhiz application is the default.
scope String The request scope, either public or mobile.
Response

The response will be token information with a 202 status code.

Errors
Status Message
400 Invalid scope requested: {scope}
400 Could not update password.
400 Invalid account information provided.

Verify phone number

POST /accounts/{account_id}/phone_verification

Send verification request or attempt to verify the phone number depending on if the verification code is present.

Request
Parameter Type Description
phone_number String ** Required** Phone number to verify
phone_country_code Integer Phone country code, defaults to 1
verification_code String Code received after previous verification request, sends code if not passed.
Response

If verification_code was ommitted, response will be a status of 204, otherwise the response will be an account model.

Errors
Status Message Code
400 Verification code does not match. verification_code_mismatch
400 Verification timeframe expired. verification_timeframe_expired
400 Phone number already in use. phone_already_in_use
400 Failed to send SMS invalid_sms
400 Failed to start verification request phone_verification_not_started
404 Invalid phone number. invalid_phone_number
404 You must use 'me' as the account_id. account_phone_verification_id

Request a verification code

POST /account_verification_codes

Send account verification request using selected delivery method.

Delivery mothod:

  • phone_number - will send verification code via SMS to the phone number sent in the request body. Note user phone number must be verified.
Request
Parameter Type Description
phone_number String Required User phone number
delivery_method String Required phone_number. Indicates how verification code should be delivered to the user.
country_code Integer Phone country code, defaults to 1.
Response

Response will be a status of 204

Errors
Status Message Code
400 Supplied delivery method is not supported. delivery_method_is_not_supported
400 Failed to send SMS. invalid_sms
429 Too many verification codes were requested. too_many_requests

Scan Codes

Get Scan Code Image

GET /scan_codes/

Get the scan code image.

Request
Parameter Type Description
code String ** Required** Code of the scan code image.
scan_code_format String ** Required** Format of the scan code image.
format String Image format of the scan code. Defaults to png.
qr_error_correction_level String Data correction level of the scan code image. Defaults to l.
margin Integer Margins of the scan code image in pixels. Defaults to 2px.
height Integer Height of the scan code image in pixels. Defaults to 256px.
width Integer Width of the scan code image in pixels. Defaults to 256px.
Response

The response will be an image of the code you requested.

Errors
Status Message
400 Please specify a scan format of QR or 1D-128B.
406 The requested format is not supported

Sellers

Lookup seller by ID

GET /seller/{seller_id}

Get the seller associated with a seller ID.

Request
Parameter Type Description
seller_id Integer ** Required** ID of the seller that you're looking up
Response

The response will be a seller model.

Errors
Status Message
404 That pricing could not be found.

Business Profiles

Tickets

Retrieve tickets

GET /tickets

Note: Please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Returns tickets associated with a given customer's account which are currently in the open or payment_failed state.

Authentication

A user authorization OAuth token of the target account is required.

Request

There are no additional fields to add to the request body.

Response

A successful response will include a 200 status code with an array of ticket model objects in the body.

Preview a ticket

POST /tickets/previews

Note: Please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Previews a ticket before creation.

Authentication

A valid OAuth token is required to use this endpoint.

Request

Parameters should be provided in the POST body.

Parameter Type Description
type String required What type of ticket to create. Supported values are: spg, osl, dtc
ticket_encoded_string String required if type is "spg" A bar or QR encoded string
ticket_type String required if type is "spg" The scanned ticket type. Supported values include: Code-39, I2/5 and QR-Code
location_id Integer required if type is "osl" or "dtc" ID of the location that the customer is parking at
external_ticket_id String required if type is "dtc" External ID of the scanned ticket
enterprise_account_id Integer ID of the Enterprise account being used to pay for the parking
saved_payment_token String Braintree token of previously saved payment method
coupon_code String Coupon code to validate for the preview
purchase_vector String Information about how the customer accessed and purchased parking
auto_apply_coupon Boolean Attempt to automatically apply any coupons which are relevant for the current user. Auto applied coupon codes will be returned in the coupon_code response and should be manually passed in when creating the ticket.
tip_amount Float allowed if type is "dtc" The amount of money that the customer would like to tip the location/attendants.
Response

A successful response will be a ticket preview model with a 200 status. Please note the warnings that can be returned from a preview. The warnings will become errors when attempting to create the ticket unless they are resolved.

Error responses
Status Code Message
400 barcode_damaged Barcode is damaged and cannot be decrypted
400 barcode_not_supported Barcode is not supported
400 invalid_pw_location This location does not support scanning tickets
400 invalid_pw_osl_location Supplied type is "osl" but the location does not support OSL tickets
400 invalid_token_type The provided token must be a user token
400 user_suspended Customer's account has been suspended
400 active_dtc_config_not_found The supplied location does not have an active DTC access control integration
404 parking_lot_not_found Parking lot not found
404 active_location_not_found An active location with the specified ID cannot be found
404 cannot_retrieve_dtc_ticket_info Cannot retrieve ticket info from the PARCS system
500 internal_server_error An internal server error has occurred
500 malformed_ticket_scan_response Resources required to complete this request are currently not available
503 scan_timed_out Resources required to complete this request are currently not available
503 unable_connect Unable to connect to the PARCS

Create a ticket

POST /tickets

Note: Please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Creates a new ticket with the open status. Creating a new ticket authorizes payment to be collected after the customer exits the facility. A customer can only have one active ticket at a time (where an active status is open, closed or payment_failed).

Authentication

If the type is dtc, then any valid OAuth token is allowed. Otherwise, a user authorization OAuth token of the target account is required.

Request

Parameters should be provided in the POST body.

Parameter Type Description
location_id Integer required if type is "osl" or "dtc" ID of the location that the customer is parking at
ticket_encoded_string String required if type is "spg" A bar or QR encoded string
ticket_type String required if type is "spg" The scanned ticket type. Supported values include: Code-39, I2/5 and QR-Code
type String required What type of ticket you're going to create. Supported values are: spg, osl, dtc
external_ticket_id String required if type is "dtc" External ID of the scanned ticket
final_price Float required if type is "dtc" Purchase price returned by POST /tickets/previews
add_on_ids String Comma-separated list of add-ons that the customer is purchasing. You can get them from the add_ons property of POST /tickets/previews.
coupon_code String Coupon code to apply against the purchase
customer_email String Email of the customer that the ticket is being purchased for
enterprise_account_id Integer ID of the Enterprise account being used to pay for the parking
purchase_vector String Information about how the customer accessed and purchased parking
quote_ids String A comma-separated string of On Demand quote IDs for the time and location that the customer is parking at. Providing quotes this way will lock in the rate for the customer.
saved_payment_token String Braintree token of previously saved payment method
payment_method_nonce String One-time use Braintree payment nonce generated by the client
scheduled_end_quote_id String required if type is "osl" The ID of the On Demand quote whose max_end time is the time that you want the ticket to be automatically closed at. Note: You also have to pass this quote_id into the quote_ids parameter to save the quote.
vehicle_id Integer The Arrive ID for a vehicle
plate_number String A vehicle license plate number
plate_state String A vehicle license plate state
tip_amount Float allowed if type is "dtc" The amount of money that the customer would like to tip the location/attendants.

At least one of enterprise_account_id or saved_payment_token must be provided when type is spg or osl. If the type is dtc, then at least one of saved_payment_token or payment_method_nonce must be provided.

One of vehicle_id or plate_number must be provided when type is not spg or dtc. If type is lpr_flash, plate_number must be accompanied by plate_state.

Response

A successful response will be a newly created ticket model with a 201 status code.

Error responses
Status Code Message
400 active_ticket Customer already has too many active tickets
400 barcode_damaged Barcode is damaged and cannot be decrypted
400 barcode_not_supported Barcode is not supported
400 invalid_payment_method The provided payment method is invalid
400 invalid_pw_location This location does not support scanning tickets
400 invalid_pw_osl_location Supplied type is "osl" but the location does not support OSL tickets
400 invalid_token_type The provided token must be a user token
400 ticket_open Ticket was already approved
400 ticket_paid Ticket was already paid
400 unverified_phone_number Customer's phone number has not been verified
400 user_suspended Customer's account has been suspended
400 no_user_supplied Please supply either a customer email or a user token
400 ticket_previously_purchased The supplied external ticket has already been purchased
400 active_dtc_config_not_found The supplied location does not have an active DTC access control integration
400 dtc_final_price_mismatch The supplied final_price does not match the calculated final_price
404 parking_lot_not_found Parking lot not found
404 active_location_not_found An active location with the specified ID cannot be found
404 cannot_retrieve_external_ticket_info Cannot retrieve ticket info from the PARCS system
500 internal_server_error An internal server error has occurred
500 malformed_ticket_scan_response Resources required to complete this request are currently not available
500 cannot_process_external_transaction Cannot process external transaction via PARCS system
503 approve_payment_timed_out Resources required to complete this request are currently not available
503 scan_timed_out Resources required to complete this request are currently not available
503 unable_connect Unable to connect to the PARCS
Coupon errors
Status Code Message
400 coupon_expired Coupon is expired.
400 coupon_first_purchase_only This promo code is only for new users
400 coupon_first_purchase_vector_purchase_only This promo code is only applicable for your first in-app purchase
400 coupon_invalid_email_domain Coupon is only valid for users with <@domain> email
400 coupon_invalid_location Coupon is not valid at this location
400 coupon_invalid_msa Coupon is only valid for parking in <city>
400 coupon_invalid_purchase_vector Coupon is only valid when purchased through <vector>
400 coupon_nonrefundable_user Coupon is invalid for this user
400 coupon_pricing_mismatch Coupon is only valid for <type> parking
400 coupon_user_required Coupon is only valid for existing users
400 invalid_coupon_code Coupon code is invalid
400 seller_coupon_mismatch Coupon is not valid for this seller
400 user_coupon_mismatch Coupon is not valid for this user
400 user_coupon_whitelist_mismatch Coupon is not valid for this user

Update a ticket

PUT /tickets/{ticket_id}

Note: Please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Updates an existing ticket.

Request

Parameters should be provided in the PUT body.

Parameter Type Description
ticket_id Integer required ID for the ticket you are trying to update.
quote_ids String A comma-separated string of On Demand quote IDs for the time and location that the customer is parking at. Providing quotes this way will lock in the rate for the customer.
scheduled_end_quote_id String The ID of the On Demand quote whose max_end time is the time that you want the ticket to be automatically closed at. Note: You also have to pass this quote_id into the quote_ids parameter to save the quote.
Response

A successful response will be the updated ticket with a 200 status code.

Errors
Status Code Message
400 osl_update_error There was a general issue updating this ticket.
403 osl_update_unauthorized You do not have permission to update this ticket.

Close out a ticket

POST /tickets/{ticket_id}/closings

Note: Please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Closes a ticket which is in the open state.

Authentication

A user authorization OAuth token of the target account is required.

Request

The following parameters should be supplied in the URL.

Parameter Type Description
ticket_id String required ID for the ticket to close.

The following parameters should be provided in the POST body.

Parameter Type Description
type String required The type of ticket to close out. Supported values are: osl
Error responses
Status Code Message
400 invalid_ticket_closing Tickets which are {ticket.status} can't be closed
404 ticket_not_found A ticket could not be found with the supplied type.

Pay a ticket

POST /tickets/{ticket_id}/payments

Note: Please contact ParkWhiz before attempting to implement the on-demand ticket flow.

Manually pay for a ticket that has entered the payment_failed status. The user may enter this state due to bad credit card information, declined payment, or other missing information required to charge the account.

Authentication

A user authorization OAuth token of the target account is required.

Request

Parameters should be provided in the POST body.

Parameter Type Description
amount String required The amount being paid - should match the value of the ticket
enterprise_account_id Integer ID of the Enterprise account being used to pay for the parking
saved_payment_token String Braintree token of previously saved payment method

At least one of enterprise_account_id or saved_payment_token must be provided.

Response

A successful response will be a ticket model with a 200 status.

Error responses
Status Code Message
400 invalid_enterprise_account_id User does not have active membership in business account
400 invalid_payment_method The provided payment method is invalid
400 invalid_saved_credit_card_id Unable to find saved credit card
400 invalid_ticket_amount Ticket amount due is '{ticket.amount}' but was given: '{amount}'
400 invalid_ticket_status Ticket is {ticket.status} and can't be paid
400 invalid_token_type Token is not authorized for this endpoint
400 no_enterprise_account_payment_method Business account does not have active payment method
400 user_suspended Customer's account has been suspended
404 ticket_not_found Could not find ticket {id}

Set the vehicle associated with this ticket

PUT /tickets/{ticket_id}/vehicles

Add information about the vehicle associated with a ticket, used to validate vehicle parking at many locations.

Authentication

A user authorization OAuth token of the target account is required.

Request
Parameter Type Description
ticket_id Integer required A ParkWhiz ticket ID
vehicle_id Integer A ParkWhiz vehicle ID
plate_number String A vehicle license plate number
plate_state String A vehicle license plate state
label String A descriptive label for the vehicle
default Boolean Whether this is the customer's default vehicle

A known, existing vehicle can be attached to the booking by specifying a vehicle_id. If the desired vehicle does not exist in the ParkWhiz system, the plate_number must be specified to add a new vehicle, with label and default optional.

Response

The response will be an array of vehicle models.

Booking Shares

Share a Booking

POST /bookings/{booking_id}/share

Allows the owner or current passholder of a booking to share access to that booking with another person (the recipient).

After a booking is created, the purchaser can choose to share access to the booking with a recipient. Once that recipient has accepted the booking share, the recipient can then share it with a third person, who could then share it with someone else, and so on.

The recipient of a booking share does not need to have an account on the service in order to access this shared booking. All that is required is an email address, so that we can send them a notification and link to the booking. You do however need an account to share a booking with another person.

Only the most recent recipient of a share for a booking can then share that booking with someone else. If you have already shared a booking with someone else, you would need to revoke your share and any shares further down the chain through the DELETE endpoint. After you've done that, you can then create a new share using this endpoint.

Request

Note: POST /bookings/{booking_id}/share requires a user authorization token.

Header Description
Authorization Bearer authorization token
Parameter Type Description
booking_id Integer required ID for the booking being shared
email String required Email address used to send the recipient a notification and link to claim the share
preserve_booking_vehicle Boolean If true, this endpoint will preserve the vehicle that is attached to the booking (defaults to false)
Response

A successful response will be a new booking share model with a 201 status code.

Errors
Status Code Message
400 param missing This will be returned only if one of the required params defined above is not returned
404 booking_not_found The booking ID provided doesn't link to a known booking, or belongs to a booking the user does not have access to
403 cannot_share_booking_already_shared This booking has been given to another user. Revoke that share before sharing booking with new user.
403 cannot_share_until_current_share_accepted This booking has already been shared, and that share must be accepted before it can be shared again.
409 booking_already_shared_with_user The user you are trying to share this booking with already has access to the booking.

Cancel booking share

DELETE /bookings/{booking_id}/share/#{booking_share_id}

This endpoint allows a booking's purchaser and any users who have been given access to the booking through booking shares to manage the current active share chain for the booking by revoking shares further down the chain from them. If a share is revoked, the user who created that share regains control of the booking, and then can share it with another person.

As an example, let's say a booking was purchased by User A, who shared it to User B, who then shared it to User C. User C cannot use this endpoint, because they haven't shared the booking with anyone. User B can revoke the share they created that gives User C access to the booking, at which point User B could then share the booking with another User D. User A can revoke the share from User B to User C AND the share from User A to User B.

Shares need to be revoked in ascending order - so in the example above, User A needs to revoke the share from User B to User C BEFORE they can revoke the share from User A to User B.

Request

Note: DELETE /bookings/{booking_id}/share/#{booking_share_id} requires a user authorization token.

Header Description
Authorization Bearer authorization token
Parameter Type Description
booking_id Integer required ID for the booking being shared
booking_share_id Integer required ID for the booking share being revoked
preserve_booking_vehicle Boolean If true, this endpoint will preserve the vehicle that is attached to the booking (defaults to false)
Response

The response will be a 204 (No Content) HTTP status.

Error responses
Status Code Message
404 booking_not_found The booking ID provided doesn't link to a known booking, or belongs to a booking the user does not have access to.
404 booking_share_not_found There is no booking share associated with the booking that has the ID passed in.
404 not_most_recent_booking_share The share is not the most recent share for the booking.
403 cannot_delete_own_share Current user cannot revoke their own access to the booking.

Models

Quote

Field Type Description
location_id String ParkWhiz ID of the location for which this quote was made.
start_time ISO 8601 Timestamp Desired parking start time. Not present for monthly parking or packages.
end_time ISO 8601 Timestamp Desired parking end time. Not present for monthly parking or packages.
min_start ISO 8601 Timestamp The earliest time that can be requested for this quote at the quoted prices. Not present for monthly parking or packages.
max_end ISO 8601 Timestamp The latest time that can be requested for this quote at the quoted prices. Not present for monthly parking or packages.
distance Distance Object Distance between parking location and the destination supplied in the q request parameter. This will not be included when bounds is your q parameter.
distance[straight_line] Object The distance between the quote's location and coordinate/event/venue/etc. It is a straight line, as the crow flies. The object supports numerous units (e.g. { "meters": 326, "feet": 1070 }).
distance[routed] Object The walking distance between the quote's location and coordinate/event/venue/etc using known streets and walking paths. The object supports numerous units (e.g. { "meters": 326, "feet": 1070 }).
seller_id Integer ParkWhiz ID of the seller of the location for which the quote was made.
disclaimers Array[Strings] A list of disclaimers for this quote.
purchase_options Array[Purchase Options] A list of purchase options for this quote. This will only be returned if the appropriate option_types are requested
on_demand_options Array[On Demand Options] A list of on demand options for this quote. This will only be returned if the appropriate option_types are requested
non_bookable_options Array[Non-bookable Options] A list of non-bookable options for this quote. This will only be returned if the appropriate option_types are requested

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the quote, they are retrieved by default.

Field Description
pw:location The quote's location
pw:event The quote's event
pw:venue The quote's venue
pw:street_parking The quote's StreetParking

Location

Field Type Description
id String ParkWhiz location ID.
name String Name of the location.
address1 String First line of location's address.
address2 String Second line of location's address.
city String City where the location is located.
state String State where the location is located.
postal_code String Location's postal code.
country String The ISO 3166-1 alpha-2 code indicating the location's country.
currency String Location's currency. Can be used to fetch result from Price object.
entrances Array[Objects] Information about the location's entrances. This will always include a "coordinates" value, but may contain other helpful information like "max_dimensions". e.g. [ { "coordinates": [lat,lon], "max_dimensions: { "inches": { "height": 71, "width" : 112 }, "human_readable": "No Vehicles Over 6' 2" in Height"}} ]
photos Array[Photos] Photos of the location.
timezone String not included by default Timezone of the location.
description String not included by default Brief description of the location.
rating_summary Rating Summary Object not included by default The location's rating, based on feedback from ParkWhiz customers.
rating_summary[average_rating] String Average rating, from 0.0 to 5.0.
rating_summary[rating_count] Integer Number of ratings that the average_rating is based off of.
scan_format String not included by default How the location scans parking passes.
display_price Boolean not included by default Whether or not you should display the price on the parking pass for this location.
validation_method String not included by default How parking is validated at this location.
directions String not included by default How customers should get to the location.
site_url String not included by default The url path for this location. E.g. "/p/new-york-parking/1234-main-street"
type String not included by default The type of location. One of commercial_garage, commercial_lot, business, residential, on_street, or unknown
phone Object not included by default e.g. { "default": "1-888-555-5555" }
hours Array[String] not included by default. This field contains a human readable set of hours for this location.
capacity Object not included by default. e.g. { "maximum": 300 }. Maximum vehicle capacity of the parking facility. If official capacity isn’t posted or accessible, this is an estimate of capacity based on manual count of stalls and/or square footage. This field will not be available unless you have a data license.
operating_hours Array[Time Periods] not included by default. This field will not be available unless you have a data license.
non_bookable_rates Array[Non-bookable Rates] not included by default. This field will not be available unless you have a data license.
outline Array[Coordinates] not included by default. Array of coordinate pairs representing the outline of the location. e.g. [[41.888387621536,-87.62872289526],[41.888173967631,-87.628725577469],[41.888179957937,-87.628242779847],[41.888391615061,-87.628256190892],[41.888387621536,-87.62872289526]]. This field will not be available unless you have a data license.
supports_booking_extension Boolean Whether or not this location supports booking extensions.
on_demand_options Object not included by default Deprecated, use on_demand_integrations instead. On demand booking options supported at this location (e.g. { "spg": true }). Possible keys include: spg, osl.
on_demand_integrations On Demand Integration Object not included by default Contains data on each on demand integration, and whether or not/how it is supported at this location. Keys are individual integration types, and include ble_flash, ble_inugo, ble_inugo_v2, osl, sod, and spg.
on_demand_integrations[type][enabled] Boolean Whether or not the location supports on demand tickets with the selected integration.
on_demand_integrations[type][config_data] Object Supporting information for the integration specific to this location. Exact structure varies from one integration type to another.
on_demand_integrations[type][validation] Validation Story Object Information about on-site parking validation for this specific on demand integration (Note: this may be different from booking validation method for the same location)
booking_integrations Booking Integration Object not included by default Availability and information about booking validation via on demand integrations at this location. Keys are individual integration types, and can include ble_inugo_v2.
booking_integrations[type][enabled] Boolean Whether or not the location supports booking validation via on demand with the selected integration.
booking_integrations[type][config_data] Object Supporting information for the integration specific to this location. Exact structure varies from one integration type to another.

Location Types

Location types represent the following:

Name Description
business The primary purpose of this location is a commercial endeavor other than parking (e.g. Hotel, Hospital, Restaurant with event parking)
residential The primary purpose of this location is housing (e.g. Condos, Apartments, Garage spaces)
commercial_lot The primary purpose of this location is parking. It is a surface lot that may or may not be covered
commercial_garage The primary purpose of this location is parking. It is a covered parking structure.
on_street The primary purpose of this location is parking. It is a group of parking spaces along the curb of a street rather than on a plot of land.
unknown We have not yet classified the type of this location

Field groups

The following field groups are available for your convenience:

Name Fields included
:default id, name, address1, address2, city, state, postal_code, entrances, photos
:address address1, address2, city, state, postal_code, country

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the booking, they are retrieved by default.

Field Description
pw:seller The location's seller

Purchase Option

Field Type Description
id String ParkWhiz ID for this Purchase Option formatted as a UUID.
start_time ISO 8601 Timestamp Desired parking start time. Not present for monthly parking or packages.
end_time ISO 8601 Timestamp Desired parking end time. Not present for monthly parking or packages.
min_start ISO 8601 Timestamp The earliest time that can be requested for this quote at the quoted prices. Not present for monthly parking or packages.
max_end ISO 8601 Timestamp The latest time that can be requested for this quote at the quoted prices. Not present for monthly parking or packages.
price Price Contains pricing in local currency (e.g. { "USD": "12.02" } or { "CAD": "25.75" }).
base_price Price Contains pricing in local currency (e.g. { "USD": "12.02" } or { "CAD": "25.75" }).
fees Array[Fee] Contains an array of fees that apply to the quote if present.
pricing_segments Array[Pricing Segments] An array of pricing segments, which your pricing is generated by.
add_ons Object Add-ons eligible to be purchased with this parking, grouped by type. e.g. {"vehicle_size": {"required": true, "options":[ ... ]}} where "options" contains Add-On models. "vehicle_size" is the most common type grouping. "required" indicates that the user needs to select one of the options from that group (again, most commonly for "vehicle_size").
cancellable_status Cancellable Status The current Cancellable Status of this purchase option.
shuttle Boolean Whether or not the location has a shuttle to the event. This will only show if the quote is for event pricing.
space_availability Space Availability Object Information about spaces for this option.
space_availability[status] String Describes the availability of spaces at this location. Either "available", "limited", or "unavailable".
space_availability[spaces_remaining] Integer If status is "limited", we will show you the number of spaces that are left at this location. Otherwise, this field will not be provided.
validation Validation Story Object Information about on-site parking validation
disclaimers Array[Strings] Pertinent parking information not displayed elsewhere on the pass/website/app For example, "Park only on levels A-D".
amenities Array[Amenities] not included by default A list of the amenities included with this purchase option.
display Display Object Information on what the preferred display options are for this quote. The current fields are as follows
display[price] String Indicates which price to display pre-purchase. Valid options are price or base_price which correspond to their respective fields in this purchase option.
restrictions Restrictons Object Any restrictions applied to this purchase option. Restrictions must be appropriately handled by the consumer to complete a purchase.
event_package_id Integer The ID of the Event Package that this is a part of.
name String The name of the event package or the pricing's Pricing Code.
shuttle_times[to_venue] Array[Shuttle Times] not included by default Shuttle times to the venue that overlap with the quote's start time.
shuttle_times[from_venue] Array[Shuttle Times] not included by default Shhuttle times from the venue that overlap with the quote's end time.
pickup_instructions String Text representation of the pricing pickup instructions
dropoff_instructions String Text representation of the pricing dropoff instructions

On Demand Option

Field Type Description
id String ParkWhiz ID for this On Demand Option formatted as a UUID.
start_time ISO 8601 Timestamp Desired parking start time. Not present for monthly parking or packages.
end_time ISO 8601 Timestamp Desired parking end time. Not present for monthly parking or packages.
min_start ISO 8601 Timestamp The earliest time that can be requested for this quote at the quoted prices. Not present for monthly parking or packages.
max_end ISO 8601 Timestamp The latest time that can be requested for this quote at the quoted prices. Not present for monthly parking or packages.
price Object Contains numerous pricing formats (e.g. { "USD": "12.02" }).
add_ons Object Add-ons eligible to be purchased with this parking, grouped by type. e.g. {"vehicle_size": {"required": true, "options":[ ... ]}} where "options" contains Add-On models. "vehicle_size" is the most common type grouping. "required" indicates that the user needs to select one of the options from that group (again, most commonly for "vehicle_size").
openable_window_start ISO 8601 Timestamp When adding an On Demand quote to a ticket, the ticket's start time must be after the quote's openable_window_start time.
openable_window_end ISO 8601 Timestamp When adding an On Demand quote to a ticket, the ticket's start time must be before the quote's openable_window_end time.
closable_window_start ISO 8601 Timestamp When this quote is added to a ticket and the ticket is closed, this quote will be taken into consideration if the ticket's end time is after the quote's closable_window_start.
closable_window_end ISO 8601 Timestamp When this quote is added to a ticket and the ticket is closed, this quote will be taken into consideration if the ticket's end time is before the quote's closable_window_end.
pricing_segments Array[Pricing Segment] An array of pricing segments, which stitch together to form your quote.
space_availability Space Availability Object Information about spaces for this option.
space_availability[status] String Describes the availability of spaces at this location. For On Demand, the status will always be available.
validation Validation Story Object Deprecated, defer to location for on demand validation. Information about on-site parking validation
disclaimers Array[String] Pertinent parking information not displayed elsewhere on the pass/website/app For example, "Park only on levels A-D".
amenities Array[Amenity] A list of the amenities included with this purchase option.
arrive_after ISO 8601 Timestamp The time that the customer has to enter the location after for this quote to be valid.
arrive_before ISO 8601 Timestamp The time that the customer has to enter the location before for this quote to be valid.
depart_after ISO 8601 Timestamp The time that the customer has to leave the location after for this quote to be valid.
depart_before ISO 8601 Timestamp The time that the customer has to leave the location before for this quote to be valid.
early_bird Boolean Whether the first of the contained pricing segments is an early bird pricing.
require_license_plate Boolean Whether any of the contained pricing segments require the customer's license plate.
min_parking_hours Decimal How long the customer has to stay parked at the location, in hours.

Price

The Price model contains a set of Key:Value pairs denoting both a currency and value pair. Generally speaking, you will receive ONE key:value pair in this object in the local currency of the item being quoted.

e.g. { "USD": "12.02" } or { "CAD": "25.75" }.

It is possible to receive more than one item in this object in the future. e.g.

{
    "USD": "12.02",
    "CAD": "25.75"
}

In either case the location model will contain a currency object which can be used by clients to infer the appropriate currency used for both display and purchase.

Fee

Field Type Description
Price Price Contains pricing in local currency (e.g. { "USD": "12.02" } or { "CAD": "25.75" }).
Type String Contains the name of the fee or charge.

Restrictions

Field Type Description
capture_plate Boolean true indicates that a license plate must be supplied with the booking call to complete a purchase

Shuttle Time

Field Type Description
start_time ISO 8601 Timestamp The time when this shuttle time information becomes valid.
end_time ISO 8601 Timestamp The time when this shuttle time information becomes invalid.
travel_time[minimum] Integer The minimum amount of time (in minutes) it will take for the shuttle to get to its destination.
travel_time[maximum] Integer The maximum amount of time (in minutes) it will take for the shuttle to get to its destination. If this doesn't come back, it means only the minimum travel time is relevant.
frequency[minimum] Integer The minimum amount of time (in minutes) between shuttles picking people up.
frequency[maximum] Integer The maximum amount of time (in minutes) between shuttles picking people up. If this doesn't come back, it means only the minimum frequency is relevant.
on_demand Boolean Whether or not the shuttle is run on demand, rather than on a set frequency. If true, the user will have to call the phone number included below.
phone[on_demand] String The phone number the user should call if the shuttle is on demand.

Non-bookable Option

Field Type Description
price Price Contains numerous pricing formats (e.g. { "USD": "12.02" }).
add_ons Object Add-ons eligible to be purchased with this parking, grouped by type. e.g. {"vehicle_size": {"required": true, "options":[ ... ]}} where "options" contains Non-bookable Add-On models. "vehicle_size" is the most common type grouping. "required" indicates that the user needs to select one of the options from that group (again, most commonly for "vehicle_size").
attributes Object e.g. { "oversize_advisory" : "OVERSIZE VEHICLES PROHIBITED", "covered": "Outdoor Lot", "type": "Self Park", "payment": "Cash Only", "services": [ "Car Wash", "Detailing", "Airport Shuttle" ]. Our parking data has a wealth of information, and only some of it is currently available via dedicated fields on this API. This attributes field will be used in short term to provide additional information, but please contact us if you find any of it useful and would like it more easily machine-readable.

Non-bookable Rates

Parking companies express rates in numerous ways. Rates can be hourly ("up to 2 hours"), time-based ("maximum to closing time"), or a combination of the two, all of which can then be superseded by daily specials, which specify arrival time ranges and/or departure time ranges and/or hourly stay ranges.

There may also be an oversize vehicle surcharge. It can either be a surcharge to the regular vehicle rates or a flat rate that overrides the regular vehicle rates.

Field Type Description
rate_period Time Period The period of time in a week through which this rate applies. When receiving multiple rates, you may find overlap. For example a garage may reset its rates every day at 6 am and you will receive rates from midnight til 6am 30 hours later for each day.
rates Array[Objects] A list of prices applicable during this time period. Each rate will typically have an 'until_time' or 'duration' value, and sometimes an 'overnight' additional charge
rates[price] Array[Price] Contains numerous pricing formats (e.g. { "USD": "12.02" }).
rates[until_time] String "HH:MM" representation of what this rate ends. For example, if a garage has a rate_period until 19:00, it might have a "max-to-close" rate of $10, which we would show as until_time="19:00".
rates[duration] Integer Maximum number of minutes allowed for the given price
rates[overnight] Object If the parking locations allows the customer to stay beyond the rate_period, it may provide this 'overnight' option. In addition to the "until_time" or "duration" rate, if the customer stays beyond the rate_period, the garage may charge this additional amount. e.g. { "rates": [ { "overnight": { until_time: "30:00", additional_cost: { "USD": "4.00" } } } ] }

For example:

[
  {
    "rate_period": {
      "start_week_day": 0,
      "start_time": "00:00",
      "end_time": "00:00",
      "end_days_later": 7
    },
    {
      "rates": [
        {
          "price": {
            "USD": "12.02",
          },
          "duration": 120,
          "until_time": "19:00",
          "overnight": {
            "until_time": "30:00",
            "additional_cost": {
              "USD": "4.00"
            }
          }
        }
      ]
    }
  }
]

Time Period

Each instance of this model represents a period of time in any arbitrary week of the year. An array of these can be used to represent when a garage is open to the public, or when specific rates are applicable.

Field Type Description
start_week_day Integer 0-6, the day of the week at which this period starts.
start_time String 'HH:MM', e.g. '13:00' for 1pm, or '00:00' for midnight.
end_time String 'HH:MM', e.g. '13:00' for 1pm, or '00:00' for midnight.
end_days_later Integer The number of days offset from the start_day that this period ends

For example, a garage that is always open might have this record for its operating hours:

{
    "start_week_day": 0,
    "start_time": "00:00",
    "end_time": "00:00",
    "end_days_later": 7
}

A rate that is eligible from 8am-8pm on Monday would be represented as

{
    "start_week_day": 1,
    "start_time": "08:00",
    "end_time": "20:00",
    "end_days_later": 0
}

Photo

Field Type Description
position Integer The order you should display the images.
alt String A description of the image for alternate text.
images Array[Image] An array of image objects. Image objects have the following fields:
images[URL] String The URL to the image.
images[width] Integer The width of the image.
images[height] Integer The height of the image.

Location Review

Field Type Description
rating Integer The rating given (1-5)
comment String The comment given
recommended Boolean Did the user recommend the location?
created_at ISO 8601 Timestamp The DateTime the review was created.

Account

Field Type Description
id Integer ParkWhiz ID of the account's user.
email String The account's email address.
first_name String The first name of the account's owner.
last_name String The last name of the account's owner.
phone_number String The phone number of the account's owner.
marketing_allowed Boolean Whether the user has opted in/out to receive ParkWhiz marketing content.

Optional fields

Field Type Description
api_key String The customer's API key.
is_reseller Boolean Whether or not the user is a reseller. Resellers cannot get refunds for their bookings or use coupons.
account_type[admin] Boolean Whether or not the user is a ParkWhiz admin.
account_type[seller] Boolean Whether or not the user is a seller. Sellers are members of and manage parking locations.
account_type[legacy_affiliate] Boolean Whether or not the user is a legacy affiliate. There is more information about the legacy affiliate program here.
is_admin Boolean Whether or not the user is an admin or not. Deprecated, use account_type[admin] instead.
created_at DateTime The Date and Time the user was created
Field Description
pw:vehicles A list of vehicles that the customer added to their account.
pw:payment_methods A list of payment methods that the customer added to their account.

Pricing Segment

Field Type Description
id Integer The ParkWhiz ID for the pricing.
start_time ISO 8601 Timestamp The start time that is used for this pricing.
end_time ISO 8601 Timestamp The end time that is used at this price.
event Event Object Information about a specific event associated with a pricing
event[id] Integer The ID of the event associated with the pricing
event[name] String The name of the event associated with the pricing
event[additional_time] Integer The amount of time in hours a booking is valid after the event ends
purchase_limit Integer The maximum number of bookings that can be made by any single account for this pricing
space_availability Space Availability Object Information about spaces for this pricing.
space_availability[status] String Describes the availability of spaces at this price. Either "available", "limited", or "unavailable".
space_availability[spaces_remaining] Integer If status is "limited", we will show you the number of spaces that are left at this price. Otherwise, this field will not be provided.

Add-On

Field Type Description
id Integer The ParkWhiz ID for this add-on formatted as a UUID
name String Name of the add-on
description String Description of the add-on
start_time ISO 8601 Timestamp The start time for this add-on
end_time ISO 8601 Timestamp The end time for this add-on
price Price Contains numerous pricing formats (e.g. { "USD": 12.02 })
items Array[String] A list of the items that come with or are covered by this add-on (e.g. ["coupe", "sedan", "hatchback"])
availability Add-On Availability Object Information about spaces for this pricing
availability[status] String Describes the availability of add-ons at this price. Either "available", "limited", or "unavailable."
availability[spaces_remaining] Integer If status is "limited", we will show you the number of add-ons that are left at this price. Otherwise, this field will not be provided.

Add-On Items

For Vehicle Size add-ons, the list of valid items includes: Coupe,Sedan,SUV,Truck/Van,Crossover,Wagon,Minivan,Hatchback

Non-bookable Add-On

Field Type Description
name String Name of the add-on
description String Description of the add-on
price Price Contains numerous pricing formats (e.g. { "USD": 12.02 }).
items Array[String] A list of the items that come with or are covered by this add-on (e.g. ["coupe", "sedan", "hatchback"])

Amenity

Field Type Description
name String The name of the amenity.
key String The short identifier of this amenity.
description String A brief description of this amenity.
enabled Boolean Whether this amenity is available with the purchased parking space.
visible Boolean Whether ParkWhiz suggests display of this amenity, even if not enabled.

Current Amenity List

Key Name Description
valet Valet Valet
attended Attended Attendant on site
reentry Reentry Allowed Reentry allowed
reentry_allowed Reentry Allowed Reentry allowed
tailgate Tailgating Tailgating allowed
unobstructed Unobstructed Guaranteed to be unobstructed
restrooms Restrooms Restrooms on site
restroom Restrooms Restrooms on site
indoor Covered Covered parking
security Security Security on site
rv Rvs Allowed RV Parking allowed
handicap Accessible Accessible parking present
shuttle Free Shuttle A free shuttle is offered
shuttle_to_venue Free Shuttle To Venue A free shuttle is available to one or more partner locations
shuttle_from_venue Free Shuttle From Venue A free shuttle is available from one or more partner locations to this location
vehicle_charging Electric Car Charging EV Charging available
price_premium Price Premium This represents a premium rate
printed_pass Printed Pass The parking pass must be printed for validation on site.

Validation Story

Field Type Description
steps OR validation_steps Array[Step Objects] A list of steps that the customer should take to validate their stay at the garage. This object will be steps except when queried as part of a Quotes request in which case it will be returned as validation_steps
step[instructions] String One piece of the instructions that the user should follow to validate their stay at the garage.
step[icon] Object Illustrative image for this validation step. It's an object with a path to the image, e.g. { "path": "/path/to/image.jpg" }.
display_message String Optional description for parking validation flow
require_license_plate Boolean Deprecated Whether validation requires the customer provide vehicle license plate information

Parking Pass Validation

Field Type Description
steps Array[Step Objects] Steps to validate parking
step[instructions] String Parking validation instructions
step[icon] Object Illustrative image for this validation step. It's an object with a path to the image, e.g. { "path": "/path/to/image.jpg" }.
display_message String Optional description for parking validation flow
require_printout Boolean Whether validation requires the customer to print their parking pass for redemption
scan_code Scan Code Object Information regarding the type, format, and correction level of the scan code
scan_code[code] String Text representation of the validation scan code
scan_code[format] String Format in which to render the validation scan code. Values will be QR or 1D-128B
scan_code[qr_error_correction_level] String Error correction level to use for QR codes
validation_colors Validation Colors Object Information on what colors to display on the parking pass. If this object is not present, color is not important for pass validation. All fields will be valid Hex Codes.
validation_colors[background] String Six digit hex code for the background color e.g. 12138C
validation_colors[font] String Six digit hex code for the font color e.g. FFFFFF
display Display Object Information on what validation data to display. When the string is required, the field should always be shown on the pass. When hidden, never show it on the pass. When optional, you can hide it on the pass, but give users the option to see it.
display[scan_code] String Should the scan code be displayed? required, optional, or hidden
display[pass_value] String Should the pass value be displayed? Note: must be requested on booking model via booking:pass_value field. required, optional, or hidden
display[pass_number] String Should the pass number be displayed? required, optional, or hidden
display[license_plate] String Should the customer license plate number be displayed? required, optional, or hidden
display[pricing_codes] String Should the pricing codes be displayed on the pass? required, optional, or hidden
display[gate_button] String Should the Vendgate gate open button be displayed on the pass? required, optional, or hidden
display[print_instructions] String Should the print instructions be displayed on the pass? required, optional, or hidden
display[full_price] String deprecated Use display[pass_value] instead.
gate_technologies Array[String] A set of supported gate technologies as strings

Booking

Field Type Description
id Integer ParkWhiz booking ID
scan_code String Text representation of parking pass QR or barcode
location_id String ParkWhiz ID of this booking's location
pricing_ids Array[Integers] List of ParkWhiz pricing IDs for this booking
event_id Integer ParkWhiz ID of this booking's event
amenity_set_id Integer ParkWhiz ID of the amenity set that comes with this booking
start_time ISO 8601 Timestamp Booked parking start time
end_time ISO 8601 Timestamp Booked parking end time
times_tbd Boolean not included by default A flag to signify that the booking has a "to be determined" date and time. If this is true, then the booking's start_time and end_time should be treated as estimates.
price_paid Price Amount the customer paid for this booking with pricing format (e.g. {"USD": 12.02 })
full_price Price Amount the seller charged for this booking, plus fees. In pricing format (e.g. {"USD": 12.02 }).
pass_value Price The value of the parking pass to the seller. In pricing format (e.g. {"USD": 12.02 }).
purchased_at ISO 8601 Timestamp When the customer purchased this booking
cancelled_at ISO 8601 Timestamp When the customer or ParkWhiz cancelled this booking.
type String The type of booking it is. Possible values: "monthly_booking", "event_booking", "transient_booking"
business_purchase Boolean Whether the booking was purchased using a Business Profile or ParkWhiz for Business Account
package Object If the booking belongs to an event package, we will return additional information about the event package
package[id] Integer ParkWhiz event package ID
package[name] String The name of the event package, for example: "Chicago Bears Season Tickets: VIP"
on_demand Boolean Was this booking a reservation (false) or on demand (true)?
share_manageable Boolean not included by default Can current user share and revoke shares they have created for this booking (true) or not (false)? (Always returns false for monthly bookings)
cancellable_status Cancellable Status not included by default The current cancellable status of the booking
cancellable Boolean deprecated Use the cancellable_now flag on the cancellable_status field instead

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the booking, they are retrieved by default.

Field Description
pw:location The booking's location
pw:event The booking's event
pw:parking_pass The parking pass used to validate this booking
pw:vehicle The vehicle attached to the booking. Not all bookings require the user to add a vehicle. It depends on the location's or pricing's validation method.
pw:receipt A convenient receipt for the booking. It contains all of the customer's purchase information.
pw:coupons The coupons that the customer used with their purchase. As of now, this will be an array of one element, but could change without notice in the future. Note: for a snapshot of coupon information at the time of purchase, look at the pw:receipt zoom instead.
pw:review The user's review of the location.
pw:booking_share The most recent non-revoked share created by the current user, if any (will always return null if authentication is not scoped to a specific user).
pw:booking_shares The current chain of active, non-revoked shares beginning with the share created by the current user and going forward in time. This would include the current user's share to a new user, any share created by that new user, and so on.

Booking Hold

Field Type Description
id Integer ParkWhiz Booking Hold ID

Booking Modification

Field Type Description
modified_at ISO 8601 Timestamp The time at which the modification took place.
previous_end_time ISO 8601 Timestamp The previous parking period end time prior to this booking modification.
modified_end_time ISO 8601 Timestamp The new parking period end time after this modification took place.

Booking Preview

Field Type Description
quote_price Price Base price of the parking (e.g. {"USD": 12.02 })
subtotal Price Price of the parking plus add-ons before discounts (e.g. {"USD": 12.02 })
final_price Price Final price to be charged to the customer for full purchase (e.g. {"USD": 12.02 })
user_credit_amount Price User credits applied to the discounted final price (e.g. {"USD": 12.02 })
coupon_amount Price Amount discounted by use of coupon (e.g. {"USD": 12.02 })
coupon_code String Coupon used to generate final_price
prior_payment Price Prior amount paid (e.g. {"USD": 12.02 }). Only applicable when extending an existing booking.

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the booking, they are retrieved by default.

Field Description
pw:booking_hold The booking hold that was created if one was created

Booking Extend Preview

Field Type Description
requested Object The requested quote with preview (e.g. {"preview": {...}, "quote": {...}) if successful, otherwise not returned.
suggested Array[Object] Suggested quotes with previews (e.g. [{"preview": {...}, "quote": {...}]) if successful, otherwise not returned.

Note: If there is no availability to extend the reservation the extend preview model may be an empty object {}.

Booking Share

Field Type Description
id Integer Parkwhiz share id
shared_status String The booking share's status. Options are accepted (the recipient accepted the share), not_shared (the booking owner has rescinded share access from the booking, or has never shared it at all), or pending (the recipient has been sent the share, but has not yet claimed it)
shared_at ISO 8601 Timestamp When the booking's owner shared access
accepted_at ISO 8601 Timestamp When the recipient accepted control of the share
deleted_at ISO 8601 Timestamp When the booking's owner rescinded access from the recipient
shared_with Array The contact info of the share's recipient. The array contains a series of hashes, each one of which represents communication method we have for the recipient. These hashes have two keys: shared_over, which for now can only be email, and value, which returns the value of the communication method (email address for email, e.g.)
share_code String The share_code that can be used in place of a booking's authorization_code when the booking share is in the accepted state. This will only be returned when the booking share is in the accepted state.

Receipt

Field Type Description
user_credit_amount[USD] Decimal How many of the customer's credits were applied to this purchase in USD.
quote_price[USD] Decimal How much the base booking cost, before add-ons were added or coupons/credits applied in USD.
subtotal[USD] Decimal The quote_price + add_on costs in USD. In other words, the whole booking price before coupons or credits are applied.
final_price[USD] Decimal What the customer actually paid. The subtotal, minus the user_credit_amount and coupon_amount.
coupon_amount[USD] Decimal How many dollars the customer's coupon took off the subtotal.
add_ons[][name] String The name of an add-on that was purchased with the booking.
add_ons[][quote_price][USD] Decimal How much the purchased add-on cost, before any coups or credits applied.
purchase_time ISO 8601 Timestamp When the customer purchased this booking
payment_type String How the customer paid for the booking. Possible values: Credit Card, PayPal, Apply Pay, Android Pay, Enterprise Account, Facebook.

Parking Pass

Field Type Description
id Integer ParkWhiz booking ID
status String Text representation of parking pass QR or barcode
pass_type String Description of the type of pass returned. May be transient, event, or mixed
pricing_codes Array[Strings] List of ParkWhiz price codes for this booking
start_time ISO 8601 Timestamp Booked parking start time
end_time ISO 8601 Timestamp Booked parking end time
arrive_by ISO 8601 Timestamp Time by which a driver must arrive for a restricted pricing
depart_after ISO 8601 Timestamp Time by which a driver must depart for a restricted pricing
min_parking_hours Integer Minimum amount of time time for which a driver must park for a restricted pricing
event_id Integer ParkWhiz event ID for the event the customer searched for when purchasing
pricing_event_id Integer ParkWhiz event ID for the event associated with the pricing the booking was purchased under
hours_after_event Float Number of hours for which a customer may remained parked after the end of the event associated with the booking. Only applicable when event_id and pricing_event_id match.
price_paid Price Amount the customer paid for this booking with pricing format (e.g. {"USD": 12.02 })
full_price Price Amount the seller charged for this booking with pricing format (e.g. {"USD": 12.02 })
amenities Array[Amenities] A list of the amenities included with this purchase option
disclaimers String Pertinent parking information not displayed elsewhere on the pass/website/app. For example, "Park only on levels A-D".
seller_id Integer ParkWhiz ID of the seller who operates the booked parking facility
active Boolean Whether the parking pass is active (true), or has been cancelled, refundeded, or has expired (false).
reseller_pass Boolean Whether the parking pass was originally booked by an identified reseller. Passes marked as such are subject to restrictions.
web_url String not included by default An authenticated URL that can be used to retrieve the parking pass by a user
pickup_instructions String Text representation of the pricing pickup instructions
dropoff_instructions String Text representation of the pricing dropoff instructions
validation Parking Pass Validation Information required to validate the pass

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the booking, they are retrieved by default.

Field Description
pw:location The booking's location
pw:event The booking's event
pw:venue The venue for the booking's event or venue of booking
pw:vehicle The vehicle for the booking
pw:seller The seller who operates the booked location
pw:partner The partner trough whom the pass was purchased
pw:add_ons The add-ons purchased with the booking
pw:booking_modifications The modifications made to this booking

Cancellable Status

Field Type Description
cancellable_now Boolean Whether or not the booking can be cancelled at the time of the API request
code String A stable identifier for the current cancellable status
message String A human readable message describing why the booking can or cannot be cancelled

Below is an enumerated list of the potential values for this object:

Code Cancellable Now Message
booking_already_cancelled false This booking has already been cancelled
booking_is_monthly false No Cancellation: Monthly parking cannot be canceled
booking_is_not_cancellable false This booking cannot be canceled
booking_times_tbd false Your event is TBD, keep your pass and we’ll update the date and time automatically. Please contact us if you need to cancel.
cancellable_during_cancellation_period true Limited Cancellation: Cancel this booking for free up to X days, Y hours, Z minutes before start time
cancellable_until_start_time true Anytime Cancellation: Cancel this booking for free up until the start time
cancellation_period_expired false No Cancellation: Your period to cancel this booking has ended
cancelling_in_progress_booking false No Cancellation: This booking will start immediately
cancelling_past_booking false No Cancellation: This booking has already occurred
customer_is_non_refundable false This booking cannot be canceled
event_package_booking_not_cancellable false No Cancellation: Parking package bookings cannot be canceled
on_demand_booking_not_cancellable false No Cancellation: Park Then Pay sessions cannot be canceled
partner_booking_not_cancellable false This partner booking cannot be canceled (or a partner defined cancellation denial message. Contact partner-support@arrive.com to set this up)

While this field shows whether or not a user can cancel a Booking, we surface this field on the Purchase Option to inform a user of the cancellable status pre-purchase. This will help users understand whether or not they will be able to cancel once they make a purchase.

Vehicle

Field Type Description
id Integer Arrive vehicle ID
label String Customer supplied label for this vehicle
default Boolean Whether this vehicle is the customer's default when booking
plate_number String License plate number of the vehicle
plate_state String License plate state of the vehicle
is_vehicle_verified Boolean Whether this vehicle has been confirmed as belonging to its user
auto_pay_authorized Boolean Whether this vehicle's user allows Arrive to automatically start LPR sessions with it

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the booking, they are retrieved by default.

Field Description
pw:bookings Bookings made with this vehicle

Venue

Field Type Description
id Integer ParkWhiz venue ID
name String Name of the venue
address1 String First line of venue's address
address2 String Second line of venue's address
city String City where the venue is located
state String State where the venue is located
postal_code String Venue's postal code
distance Object Distance to the venue from the search coordinates, if provided (e.g. { "miles": 0.75, "meters": 1207.01 })
timezone String not included by default Time zone of the venue
description String not included by default Brief description of the venue
venue_type String not included by default Category of the venue (e.g. arena, park, etc.)
website URL not included by default URL of the venue's non-ParkWhiz website (e.g. http://soldierfield.net)
coordinates Array not included by default Coordinates of the venue (e.g. [ lat,lon]).
msa String not included by default Name of the major city this venue is within
primarily_transient Boolean not included by default Whether this venue has events (false) or is for transient parking only (true)
seo_meta Object not included by default SEO data about the venue, including title and description
enhanced_airport Boolean not included by default Whether or not the venue is an enhanced airport
country String not included by default The ISO 3166-1 alpha-2 code indicating the venue's country

The following resources can be retrieved with the zoom parameter as described in the section on linking

Field Description
pw:upcoming_events A list of upcoming events that are at the venue. It is sorted by the event's starting time, soonest event first. It will return a maximum of 100 events by default, but is configurable by supplying a zoom_resource_limits URL parameter, such as zoom_resource_limits=pw:upcoming_events:20.

Event

Field Type Description
id Integer ParkWhiz event ID
name String Name of the event
venue_id Integer ParkWhiz venue ID
start_time ISO 8601 Timestamp The event's start time
end_time ISO 8601 Timestamp The event's estimated end time
times_tbd Boolean not included by default A flag to signify that the event has a "to be determined" date and time. If this is true, then the event's start_time and end_time should be treated as estimates.
event_type String not included by default Category of the event (e.g. concert, baseball, etc.)
site_url String not included by default The url path for this event. E.g. /house-of-blues-chicago-parking/classic-rock-night-12345/
partner_events Array[Partner Event] not included by default A list of Partner Events corresponding to this event.

The following resources can be retrieved with the zoom parameter as described in the section on linking

Field Description
pw:venue The event's venue

Field groups

The following field groups are available for your convenience:

Name Fields included
:default id, name, venue_id, start_time, end_time
:times start_time, end_time

Partner Event

Field Type Description
partner_event_id String The Event ID from an external partner.
event_source_partner Event Source Partner Object The partner attributes associated with the external Partner Event ID. See Event Source Partners for valid partners.
event_source_partner[id] Integer The Arrive ID of this partner.
event_source_partner[name] String The name of this partner.

Hub

Field Type Description
id Integer ParkWhiz hub ID.
coordinates Array Center coordinates of the hub (e.g. [ lat,lon]).
name String Display name of the hub, ex: "Chicago Loop".
availability[monthly_availability] Space Availability Object not included by default Availability information for monthly parking spots. Note: This property is expensive to obtain.
city String not included by default The city where the hub is located.
country String not included by default The ISO 3166-1 alpha-2 code indicating the hub's country.
postal_code String not included by default The postal code that is nearest to the coordinates of the hub. Note: This property is expensive to obtain.
state String not included by default State that the hub is in.

Coupon

Field Type Description
id Integer ParkWhiz coupon ID
description String A short description of the coupon
dollar_discount String The discount that the coupon provides the customer, in dollars
pricing_type String Whether the coupon applies to daily parking or monthly parking
label String A short label for the coupon
expiration_date ISO 8601 Timestamp When the coupon expires

Payment Method

In this context, payment methods will only refer to Credit Cards or ParkWhiz For Business accounts. It will also refer to a user's Business Profile, which is technically a credit card.

Common fields:

Field Type Description
id String ParkWhiz payment method ID. This is used as a saved_payment_token when creating a booking
type String What type of payment method it is. Either credit_card or Enterprise. Enterprise refers to PW4B.
required_license_plate Boolean Whether or not the pricing requires a license plate.
is_default Boolean Whether or not this is the user's default payment method.

Credit card fields:

Field Type Description
last_4 String The last 4 digits of the credit card.
label String The label that the customer chose to give the credit card.
card_type String The type of credit card the customer saved.
expiration_month Integer The month that the credit card expires.
expiration_year Integer The year that the credit card expires.
postal_code String The zip code that the credit card is registered under.

ParkWhiz For Business fields:

Field Type Description
account_name String The client selected name for the account.
account_id Integer The PW id for the enterprise account that the credit care belongs to.

Sellers

Field Type Description
id Integer ParkWhiz seller ID if available.
name String Seller public name.

Ticket

Field Type Description
id Integer The id of the ticket
type String The type of the ticket (e.g. "spg" or "osl")
ticket_amount Price The amount the customer was charged for parking (e.g. ticket_amount: { USD: "15.00" })
coupon_code String The coupon code that will be used to discount the purchase
parking_transaction_id String The transaction id associated with this ticket
on_site_ticket_id String The ticket number provided by the parking system
parking_start DateTime The time the customer began parking
parking_end DateTime The time that the customer exited the facility
status String The current status of the ticket

Ticket Statuses

The status for a ticket will generally follow the below path unless there is a problem:

open -> closed -> reconciled

Status Description
open Parking has started
closed Parking has ended but the customer has not yet been charged
payment_failed Parking has ended and charging the customer's payment method failed or the customer has an overage
invalidated The parking ticket has been invalidated
reconciled Parking has ended and the customer's payment method was successfully charged

Payment Failed

If the ticket has a status payment_failed, either the user's payment method failed, or the ticket was applied to a booking and there was an overage charge. Overage charges occur when the user overstays their booking or arrives before the booking start time. In either of these cases, the Ticket model will return additional information about the failed payment:

Field Type Description
payment_failed_reason String The code representing the reason why the user was charged an overage (or payment_failed for failed payments).
previous_credit_applied Price The amount of money already paid for a ticket/booking in a failed payment or overage flow.
coupon_amount Price The coupon amount that was already applied to a ticket/booking in a failed payment or overage flow.
credit_amount Price The amount of credits the user can still apply towards the ticket in a failed payment or overage flow.
final_price Price The price that the customer still owes in a failed payment or overage flow (minus the credit_amount).

Below is an enumerated list of the possible values for payment_failed_reason:

Payment Failed Reason Description
payment_failed The user's credit card could not be charged
entered_before_and_exited_after_booking_times The user entered the location before their booking started and exited after their booking ended.
entered_before_booking_start The user entered the location before their booking started.
exited_after_booking_end The user exited the location after their booking ended.
entered_after_arrive_by_time The user entered the location after their booking's designated arrive by time.
exited_before_depart_after_time The user exited the location before their booking's designated depart after time.
did_not_reach_minimum_stay The user did not stay for the minimum amount of time required by the location.

The following resources can be retrieved with the zoom parameter as described in the section on linking.

Field Description
pw:booking The ticket's booking (only present after a Ticket has been closed)
pw:location The ticket's location
pw:scheduled_end_quote The quote used to schedule the end of the ticket (using the quote's max_end)
pw:vehicle The vehicle that the customer is parking with

Ticket Preview

Field Type Description
coupon_code String The coupon code being applied to this preview
on_site_ticket_id String The ticket number provided by the parking system
ticket_start_time DateTime The time the ticket parking began. This will not return for OSL previews.
external_validation_applied Boolean Whether or not a validation has been applied to the ticket
grace_period_minutes Integer The number of minutes a user has to exit the parking lot after purchase
final_price Price Final price to be charged to the customer for full purchase (e.g. {"USD": 12.02 })
warnings Array A list of warnings indicating problems which will prevent a successful checkout (e.g. [{ code: 'invalid_payment_method', message: 'The provided payment method is invalid'}])
add_ons Object Add-ons eligible to be purchased with this parking, grouped by type. e.g. {"vehicle_size": {"required": true, "options":[ ... ]}} where "options" contains Add-On models. "vehicle_size" is the most common type grouping. "required" indicates that the user needs to select one of the options from that group (again, most commonly for "vehicle_size").

Warnings

Code Message
active_ticket Customer already has an active ticket which needs to be closed out
invalid_payment_method The provided payment method is invalid
unverified_phone_number Customer's phone number has not been verified

The following resources can be retrieved with the zoom parameter as described in the section on linking. As these resources contain needed information about the quote, they are retrieved by default.

Field Description
pw:location The ticket preview's location
pw:quotes An array of quotes that guarantee prices when a user closes their ticket. They must be passed in as quote_ids when opening a ticket. Quotes returned here will not follow fields and zooms passed in.

Suggested View

Field Type Description
data Array[Quotes] A subset of quotes to display on the map optimized for relevancy and the search type
nearby_metros Array[Hub] A list of nearby metro areas. May be included if no quotes are returned
nearby_venues Array[Venue] A list of nearby pois. May be included if no quotes are returned

a

Street Parking

Field Type Description
streets Array[String] Contains a list of the streets included in this parking recommendation.
type String The type of street parking recommendation
timezone String The timezone for this street area
origin Origin Object The recommended point from which to begin navigating along the described route
origin[coordinates] Coordinates A set of coordinates
origin[heading] String A text description of the headng.
origin[bearing] String A text descrition of the bearing.
origin[street] String The name of the origin street.
stop_loss StopLoss Object The point at which you are recommended to abandon looking for parking along this route
stop_loss[coordinates] Coordinates
stop_loss[radius] Float The overall radius to monitor originating from the stop loss coordinates to consider abandoning looking for street parking along this route
stop_loss[distance] Float The maximum distance of travel to consider abandoning looking for street parking along this route
probability Integer The overall probability of finding parking along the described route
walking_distance Distance Object The walking distance from this recommended segment to the destination
itinerary Array[String] *This is a deprecated field. Use itineraries * A set of directions to navigate the parking recommendation from the origin
itineraries Itinerary Structured data representing a set of directions to navigate the parking recommendation from the origin
potential_spots Integer The number of potential spots along this route
segments Array[StreetSegment] The set of street segments contained in this recommendation

Itinerary

Field Type Description
oneliner String A top level description of the itinerary
directions Array[String] An array of individual steps along the intinerary describing the action to take.
structured Array[StructuredItinerary] A set of structured data describing each point of the itinerary

Structured Itinerary

Field Type Description
turn String Will be one of start, left, right describing the direction of the turn
bearing Integer Describes the bearing
heading String Describes the Cardinal Direction heading
Windrose String Describes the Windrose
street String The name of the street
intensity String Describes the intensity of the turn. Will be one of turn, slight, sharp
angle Integer Describes the angle of the turn
feature Integer Represents the index (0 indexed) of the StreetSegment associated with this itinerary item
coordinate Integer Represents the coordinate index (0 indexed) of the StreetSegment coordinates associated with this itinerary item
distance Integer Describes the distances to travel along the segment in meters

Street Segment

Field Type Description
id String GUID
osm_id String Open Street Map ID
geometry GeoJSON GeoJSON representation of the street segment
timezone String Local timezone
capacity Capacity Capacity of segment if available
partitions Array[Partition] A set of partitions included in this segment

Partition

Field Type Description
geometry GeoJSON GeoJSON
max_price Price This defines the maximum parking cost found within a partition for a given date / time.
price Price This defines the expected cost found within a partition for a given date / time.
capacity Capacity
restrictions StreetRestrictions

Geo JSON

Field Type Description
type String The type of GeoJSON represented. Types can be Point, LineString, Polygon, MultiPoint, MultiLineString, and MultiPolygon.
coordinates Array[Coordinates] An array of coordinates describing the area.

Street Restrictions

All street parking is represented by GeoJSON and left and right can be determined by looking at the direction of travel from the first coordinate to subsequent coordinates.

Field Type Description
left_allowed boolean Indicates whether parking is available on the left side of the street. Possible values are allowed, prohibited and unknown
right_allowed boolean Indicates whether parking is available on the right side of the street. Possible values are allowed, prohibited and unknown
left Array[String] A set of readable restrictions for the left side of the street
right Array[String] A set of readable restrictions for the right side of the street

Recommendation

Field Type Description
reasons Array[Reason] A list of reasons that influenced this recommendation
summary Summary A summary statement regarding the reasons that a recommendation was given
data Quote A Quote for this recommendation

Statements

Field Type Description
general Statement A statement describing the overall parking environent
onstreet Statement A statement describing the onstreet parking environent
offstreet Statement A statement describing the offstreet parking environent
price Statement A statement describing the overall pricing of known parking
public Statement A statement describing the public parking environent
city_center Statement A statement describing the city center parking environent
ev_charging Statement A statement describing known ev charging

Statement

Field Type Description
short Array[String] Contains one or more statements
more Array[String] Contains one or more statements elaborating on the short statements or providing additional context or information

Reason

Field Type Description
code String The reason code
text String Text describing the meaning of the reason code

Reason Codes

Code Text
cheapest This location is the cheapest available.,
closest This location is the closest to the destination.,
fastest This location gets you parked and to the destination quickest.,
fastest_park This location should get you parked the quickest.,
affair This location has been identified by the partner as recommended for this event.,
parking_probability_very_low It is unlikely you will find parking,
parking_probability_low There is a low chance to find parking,
parking_probability_medium There is a chance to find parking,
parking_probability_high There is a good chance to find parking,
parking_probability_max Parking is available,
tradeoff_price_eta This is the best balance between cost and eta.,
walking_eta This location is the quickest walk to your destination.,
weather_parking Weather looks to be poor and this location is covered or underground.,
weather_walking Weather looks to be poor and this location is a close walk to the destination.,

Probability

Field Type Description
probability Integer 0 - 100 representation of calculated probability of finding parking
confidence Ingeter 0 - 100 representation of calculated confidence in probability

Summary

Field Type Description
short String Contains one or more statements
more String Contains one or more statements elaborating on the short statements or providing additional context or information
structured Array[StructuredSummary] An array of strucuted data for this summary statement

Structured Summary

Field Type Description
readable ReadableSummary Contains a readable statement of this summary with short and more
artifacts SummaryArtifacts Contains the artifacts that contributed to the composition of the ReadableSummary
rule_id String A string represention of the ID matching the rule that generated this statement. Note: Rule ids may change over time, however promised to be unique in the context of a single request.
rule_name String A string representation of the name of the rule that generated this statement. Note: Rule names are provided as hints only, and may also change over time.
priority Float The execution priority of the parkig-logic Rule which has created this caption (0 is the highest priority). Note: logarthmic scale.
rank Float The value of the recommendation rank after application of this specific rule. This value relates to factor calculation directly.
factor Float The weight with which this specific item influenced the final recommendation rank.
rarity Float The rarity of this specific message measured between [0..1]

Readable Summary

Field Type Description
short String Contains one or more statements
more String Contains one or more statements elaborating on the short statements or providing additional context or information

Summary Artifacts

Field Type Description
long string Contains a string with variables that was used to build the ReadableSummary object
values map[String]String Contains the key:value pairs to substitute the variables in long with their appropriate values.
Last updated March 11, 2024