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=publicwhich will yield a response like:
{
"access_token": "new_token_12345",
"token_type": "bearer",
"expires_in": 31557600,
"scope": "public",
"created_at": 1486143527
}expires_ingives the number of seconds until the token expires (tokens expire a year after they are granted).scopethe authorization scope given to this token. See the scope section.created_atwhen 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=publicwhich 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=yourSecurePasswordwith 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 Sign 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=123456with 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=partnerOn 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=internalwhich 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_TOKENThe 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=internalwill 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 publicResponse:
{
"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 publicResponse:
{
"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:ascWe 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=nameMultiple sorting parameters can be supplied and separated with with spaces. It will look similar to:
?sort=name:desc distancewhich 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=countwhich 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:5In 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,entrancesYou 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_summaryNamespacing 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_summaryIt 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=trueparam, 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:
nameto indicate the name of the add-onpriceto indicate the price of the add-onavailabilityto indicate whether this type of parking is available or notitemsthat 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. |
This is a deprecated field. Use returns Will return only facilities that are mobile enabled. Default false. |
||
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. |
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_bookableBounds 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_bookableFor 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_bookableCoordinates, 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_mobileCoordinates, 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_bookableResponse
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"}) |
Related models
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 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 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. |
| event_id | Integer | The Event ID to associate with the booking. The event will only be associated with the booking if the parking period overlaps with event time in some way. |
| 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 |
| 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:
- The booking
authorization_code - A user authorization OAuth Bearer Token for the user whose tickets you are accessing
- A partner client credentials OAuth Bearer Token for the partner attributed with the booking
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 |
|---|---|---|
| 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 |
|---|---|---|
| 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 a list of recommended bookings
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 |
|---|---|---|
| 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 |
|---|---|---|
| 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 |
Related models
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. |
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 |
Related models
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. |
| 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. |
| 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 |
Related models
| 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 |
| 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 |
| 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 |
deprecated Use the cancellable_now flag on the cancellable_status field instead |
Related models
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. |
Related models
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 |
Related models
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 |
| color | String | The color of the vehicle |
| make | String | The make of the vehicle |
| classification | String | The type of the vehicle |
| engine_type | String | What makes the car move |
| plate_type | String | What type of license plate is on the car. |
| temporary | Boolean | Whether this vehicle is temporary or not. Temporary vehicles will not be verified as owned by the account and cannot be auto_pay_authorized. |
Related models
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 |
Related models
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. |
Related models
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. |
Related models
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 |
Related models
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 |
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 |
| 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. |