API Response Structure
This page describes the response structure of successful API queries
Unless explicitly mentioned, JSON will be returned in all responses.
Each successful query response will be returned in a standard structure. The following table provides an explanation of each key/value that is returned
Standard JSON response:
account
This part of the returned JSON provides details about your account subscription. It is intended to provide confidence that your credentials and subscription plan are correct, however, it also provides a running total of the number of queries you've made this month.
The details return in the account section should be safe-guarded and not published on your system for consumption
Standard JSON response:
Key
Response Description
subscriber
Your Subscription Key used to process this query. You can rotate your Subscription Key (and API Key) from the customer portal
name
Your name as defined in your profile in the Customer Portal.
subscription_active
Will always return as 1 (for Yes) if a query is successful.
subscription_plan_name
The name of the plan you are subscribed to. Note, if you have multiple subscriptions, the plan name is the one associated with the Subscription Key used.
subscription_renewal_date
The date your plan will renew and next payment will be taken. If a cancellation has been requested this value will be replaced with subscription_expiry_date
no_api_calls_allowed
This shows the total number of API calls allowed for this month as defined by the subscription plan. In the event we increase the number allowed, this will be reflected here
np_api_calls_used
The number of API calls made this month that have counted against your subscription. Note - this is the number of calls made prior to executing this query. The number of queries performed that haven't applied against your quota can be seen in the Customer Portal.
response
This section provides a 'technical' response code intended to provide the developer with some basic 'debug' information to explain the reason for the code. The message value will contain any comments returns from the query.
Standard JSON response:
Note - The code values that are returned mirror HTTP response codes. HTTP response codes are also set but we would recommend parsing this response for errors rather than relying on the HTTP response code.
We don't recommend these details are published on your system
code
code_description
message / details
200
Ok
The query was successful irrespective of whether the results give a positive response
400
Bad Request
Likely returned if a parameter is missing from a query. The message value will detail the parameter that is missing. Check this documentation for the correct parameter values.
401
Unauthorized
It's likely your Subscription Key or API Key are not valid
403
Forbidden
Your subscription doesn't allow for the call made or you've implemented Whitelist restrictions in your control panel - please check these settings allow your system to connect
404
Not Found
You've requested a page or search query that doesn't exist. PLEASE NOTE - we also return a 404 in the event that no results have been found
422
Unprocessable
The structure of the query is correct, but one of the parameters contains an invalid value. Where possible, the system will use default values to mitigate but this isn't always possible.
503
Maintenance
We're currently undertaking some maintenance. We currently have a nightly maintenance routine that runs for circa 1 hour.
search
This section of the JSON response returns details about the query that has been requested. Depending on the type of query, the array contained within will change. In general, if a car-based search has been performed then the car_searched array will be returned. If a buggy-based query is performed then the buggy_searched array will be returned. In some cases, both are returned and in some cases only a basic response is provided (for example where the query doesn't require any parameters to be provided)
Standard JSON response:
Key
Options
Default
Response Description
carID or VRM
N/A
N/A
Returns the parameter you provided as part of your search. Note - if you've used a carID this should not be published or be made available on your website either rendered or as part of the page source code.
manufacturer model body_type detailed_model_name years
N/A
N/A
Indicates the car associated with the carID or vrm parameter. Intended to provide some comfort to your users that the correct car has been found/used in the search
boot_measurement_available
Yes No
N/A
"Yes" indicates that we have at least the core boot measurements available with which to perform a search. "No" indicates that we have not captured the measurements of this car model yet and therefore searches that require this car will fail.
lower_boot_measurments_available
Yes No
N/A
"Yes" indicates that the car model has a removable floor or lower boot area that is useful for meaningful storage, and the API can use the measurements. "No" either indicates that there is no lower boot area for this model or the API doesn't have the measurements captured yet.
3rd_row_measurements_available
Yes No
N/A
"Yes" indicates that the car has a 3rd row of seats (likely a 7-seater vehicle) and that the API can use the measurements for the space behind the 3rd row. "No" either indicates that the car does not have a 3rd row of seats or that the API doesn't have the measurements captured yet.
measurements_requested
boot lower ceiling max_height seats_flat 3rdboot 3rdceiling
boot
brand_name buggy_model_id buggy_model_name
buggy_variant_name
N/A
N/A
Indicates the buggy details searched
buggy_folded_dimensions
N/A
N/A
The folded measurements of the buggy shown in cm. Length, width, height.
buggy_dimensions
0 - Standard Measurements 1 - Smallest Measurements
0 - Standard Measurements
images: buggy_image_url
N/A
N/A
images: buggy_thumbnail
N/A
N/A
results
This section of the JSON response contains the results returned by each query. Each query returns a different results array - please refer to the documentation for each query.
Standard JSON response:
Key
Options
Default
Response Description
error_message
N/A
N/A
Provides a 'customer friendly' response that might be of use to your customers if a search has not completed successfully.
Last updated