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": {
        "subscriber": "YOUR_SUBSCRIPTON_KEY",
        "name": "YOUR NAME"
        "subscription_active": "1",
        "subscription_plan_name": "Executive",
        "subscription_renewal_date": "15-01-2021",
        "no_api_calls_allowed": 2000,
        "no_api_calls_used": "209"
    },
    "response": {
        "code": "200",
        "code_description": "Ok",
        "message": "Query successful"
    },
    "search": {
        "car_searched": {
            "carID": "XXXXXXX",
            "vrm": "",
            "manufacturer": "PEUGEOT",
            "model": "508",
            "body_type": "Hatchback",
            "detailed_model_name": "1.6 Hybrid Allure Premium 5dr e-EAT8",
            "years": "2020 - ",
            "boot_measurement_available": "Yes",
            "lower_boot_measurements_available": "No",
            "third_row_measurements_available": "No",
            "measurements_requested": "boot"
        },
        "buggy_searched": {
            "brand_id": "35"
            "brand_name": "Phil and Teds",
            "buggy_model_id": "557",
            "buggy_model_name": "mod",
            "buggy_variant_name": "Capri",
            "buggy_folded_dimensions": "71.00 x 57.00 x 32.00",            
            "buggy_dimensions": "Standard measurements",
            "images": {
                "buggy_image_url": "https://ik.imagekit.io/mybuggymycar/buggy-images/tr:n-mbmcdefault300/brands/phil-and-teds/557-phil-and-teds-mod-cap...",
                "buggy_thumbnail": "https://ik.imagekit.io/mybuggymycar/buggy-images/tr:n-mbmcthumbnail/brands/phil-and-teds/557-phil-and-teds-mod-cap..."
            }   
        }
    },
    "results": [
        {
            "willItFit": "Yes",
            "fitLayingDownLR": "Yes",
            "fitLayingDownFB": "Yes",
            "fitLayingDownOnSide": "Yes",
            "fitLayingDownOnEnd": "Yes",
            "error_message": "The search was successful"
        }
    ]
}

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:

{
    "account": {
        "subscriber": "YOUR_SUBSCRIPTON_KEY",
        "name": "YOUR NAME"
        "subscription_active": "1",
        "subscription_plan_name": "Executive",
        "subscription_renewal_date": "15-01-2021",        
        "no_api_calls_allowed": 2000,
        "no_api_calls_used": "209"
    }
}

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:

{

    "response": {
        "code": "200",
        "code_description": "Ok",
        "message": "Query successful"
    }
}

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:

{
    "search": {
        "car_searched": {
            "carID": "xxxxxxx",
            "vrm": "",
            "manufacturer": "PEUGEOT",
            "model": "508",
            "body_type": "Hatchback",
            "detailed_model_name": "1.6 Hybrid Allure Premium 5dr e-EAT8",
            "years": "2020 - ",
            "boot_measurement_available": "Yes",
            "lower_boot_measurements_available": "No",
            "third_row_measurements_available": "No",
            "measurements_requested": "boot"
        },
        "buggy_searched": {
            "brand_id": "35"
            "brand_name": "Phil and Teds",
            "buggy_model_id": "557",
            "buggy_model_name": "mod",
            "buggy_variant_name": "Capri",
            "buggy_folded_dimensions": "71.00 x 57.00 x 32.00",            
            "buggy_dimensions": "Standard measurements",
            "images": {
                "buggy_image_url": "https://ik.imagekit.io/mybuggymycar/buggy-images/tr:n-mbmcdefault300/brands/phil-and-teds/557-phil-and-teds-mod-cap...",
                "buggy_thumbnail": "https://ik.imagekit.io/mybuggymycar/buggy-images/tr:n-mbmcthumbnail/brands/phil-and-teds/557-phil-and-teds-mod-cap..."
            }
        }
    }
}

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

Details the measurements requested to be used in the search parameters (see Car Queries for more details).

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

Details the measurements requested to be used in the search parameters (see Buggy Queries

images: buggy_image_url

N/A

N/A

Will only be returned in 'buggy_searched' for Will A Buggy Fit and Will A Buggy Fit In A Space searches. A url to a 300x300 image of the buggy searched for. The url incorporates a signature that changes on each search

images: buggy_thumbnail

N/A

N/A

Will only be returned in 'buggy_searched' for Will A Buggy Fit and Will A Buggy Fit In A Space searches. A url to a thumbnail (150x150) image of the buggy searched for. The url incorporates a signature that changes on each search

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:

{
    "results": [
        {
            "willItFit": "Yes",
            "fitLayingDownLR": "Yes",
            "fitLayingDownFB": "Yes",
            "fitLayingDownOnSide": "Yes",
            "fitLayingDownOnEnd": "Yes",
            "error_message": "The search was successful"
        }
    ]
}

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.

PreviousAuthenticationNextBuggy Queries

Last updated