TECHNICAL DOCUMENTATION

Learn about deploying and managing your FUEL products.


The Fuel API is developed around REST principles. It is designed using predictable, resource-oriented URLs and HTTP response codes to indicate errors. Fuel uses HTTP features, such as HTTP authentication and HTTP verbs, which should make integration with standard HTTP clients much easier. JSON or XML will be returned in all responses, depending on what is set in the {format} section of the URL patterns below.

API Endpoint: https://api.fuelapi.com/

Resource URL Patterns:
/v1/{format}/modelYears/
/v1/{format}/makes/
/v1/{format}/models/
/v1/{format}/products/
/v1/{format}/vehicles/
/v1/{format}/vehicle/
/v1/{format}/products/

AUTHENTICATION

Authentication to the Fuel API is done by providing an application's API key in the request. Applications and their respective API keys can be managed in the API section of your account. API keys hold specific privileges, so they should be kept secret.

Authentication to the API occurs via HTTP Basic Authentication. You provide your API key as a basic auth username, with no password required. All requests to the API must be made over HTTPS, and you must authenticate using an API key for every request.

$ curl https://api.fuelapi.com/v1/json/makes/?year=2014 -u daefd14b-9f2b-4968-9e4d-9d4bb4af01d1:
Output:
                    [
                        {
                            "id": "7942",
                            "created": "2013-10-04 13:01:35",
                            "modified": "2013-12-04 22:25:25",
                            "trim": "Sport",
                            "num_doors": "4",
                            "drivetrain": "FWD",
                            "bodytype": "CUV"
                        },
                        {
                            "id": "7951",
                            "created": "2013-10-17 17:31:06",
                            "modified": "2013-12-10 23:56:51",
                            "trim": "Grand Touring",
                            "num_doors": "4",
                            "drivetrain": "FWD",
                            "bodytype": "CUV"
                        },
                        {
                            "id": "7943",
                            "created": "2013-10-04 13:01:35",
                            "modified": "2013-12-04 22:25:25",
                            "trim": "I Grand Touring",
                            "num_doors": "4",
                            "drivetrain": "FWD",
                            "bodytype": "sedan"
                        },
                        ...
                     ]
                        

You may also authenticate by providing your API Key in the request url (as api_key).

$ curl https://api.fuelapi.com/v1/xml/vehicles/?api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1&year=2014

ERRORS

Fuel provides conventional HTTP response codes to indicate errors. Not all errors map cleanly into HTTP response codes, so when a request is valid but is not successful, the API will return a 402 error code.

HTTP Status Code Summary:
200 OK - Everything worked as expected.
400 Bad Request - Likely a missing required parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - Parameters were valid but the request failed.
404 Not Found - The request doesn't exist.
500, 502, 503, 504 Server errors - something went wrong on Fuel's end.

Product Data

/v1/{format}/products/
REQUIRED: none
OPTIONAL: showShotCodes (set to 1, this will show available shot codes for the products. For now, this only applies to Stills, as color data requires a vehicle to be specified)
OPTIONAL: showProductFormats (set to 1, this will show more detailed product format information)
EXAMPLE: https://api.fuelapi.com/v1/json/products/?api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1&showShotCodes=1

Output:
[
                    {
                        "id": "1",
                        "created": "2013-10-17 17:42:06",
                        "modified": "2014-04-29 02:26:24",
                        "name": "Stills",
                        "color_product": "0",
                        "shotCodes": [
                            {
                                "code": "037",
                                "type": "angle",
                                "description": "Driver's side profile with drivers side door open. "
                            },
                            {
                                "code": "038",
                                "type": "angle",
                                "description": "Passenger's side view, sliding door open (vans only). "
                            },
                            {
                                "code": "039",
                                "type": "angle",
                                "description": "Inside of driver's side open door, window open. "
                            },
                            ...
                        

VEHICLE PRODUCTS

There are two ways to obtain vehicle-specific assets.

Preferred method:
/v1/{format}/vehicle/{vehicleID}

Alternative method (deprecated):
/v1/{format}/vehicle/{VIN}

REQUIRED: vehicleID or VIN
OPTIONAL: productID (show only assets for a particular product) - This is required if you wish to specify a shot code or color.
OPTIONAL: shotCode (used to retrieve a single shot – see SHOT CODES table below for possible values)
OPTIONAL: color (can be OEM color value, simple color name, or hex RGB value)
OPTIONAL: proto (http or https - indicates the asset url protocols in the response, overrides the default setting for the application)

Examples
Default behavior, but slightly changed response format
https://api.fuelapi.com/v1/json/vehicle/1078/?api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1

Shows Stills images for this vehicle
https://api.fuelapi.com/v1/json/vehicle/1078/?api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1&productID=1

Shows Stills images of shot code 113
https://api.fuelapi.com/v1/json/vehicle/1078/?api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1&productID=1&shotCode=113

Shows black color images
https://api.fuelapi.com/v1/json/vehicle/1078/?api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1&productID=2&color=black

Note: not all VINs will have matching vehicles. When a VIN cannot be found, you should use the following method to determine vehicleID.

VEHICLE ID

In order to determine the vehicleID, you must call the /vehicles endpoint to search our image library for vehicles matching your criteria.

Recommended Method:
/v1/{format}/vehicles

REQUIRED: year (the 4-digit model year, 1998-present)
REQUIRED: make (the vehicle brand)
REQUIRED: model (the model name)
OPTIONAL: body (the vehicle body style)
OPTIONAL: doors (the number of doors**)
OPTIONAL: drive (the vehicle drive type)
OPTIONAL: trim (the vehicle trim package)
RETURNS: list of vehicles matching given criteria

Optional parameters filter the results. If you are trying to match a single vehicle please supply all parameters.

Due to differences in the way Trim packages are identified, it may be desirable to not pass the trim parameter and retrieve vehicleIDs all available trim packages for similar vehicles in our library. For “base” trim, set the trim parameter to an empty string.

** The number of doors may be reported differently across data providers (esp. for hatchbacks and wagons)

$ curl https://api.fuelapi.com/v1/json/vehicles/?year=2016&model=silverado%201500&make=chevrolet&body=crew%20cab%20pickup&drive=4x4&doors=4&trim=LS&api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1

Alternative Method (deprecated):
/v1/{format}/vehicles

REQUIRED: none
OPTIONAL: year, makeID, modelID
RETURNS: list of vehicles matching given criteria. Data hierarchy is as expected (ie. modelID trumps makeID and year, if all are presented).

$ curl https://api.fuelapi.com/v1/json/vehicles/?modelID=3724 -u daefd14b-9f2b-4968-9e4d-9d4bb4af01d1

To get make and model data:

/v1/{format}/modelYears/
REQUIRED: none
OPTIONAL: none
RETURNS: list of available model years


/v1/{format}/makes/
REQUIRED: none
OPTIONAL: year
RETURNS: list of makes matching criteria


/v1/{format}/models/{makeID}
REQUIRED: makeID
OPTIONAL: year
RETURNS: list of models for a given make

SHOT CODES

Use the following tool to look up shotcodes by their description.

Shot Code Description Image

091-100 (Exterior Bonus Shots) and (101-110 Interior Bonus Shots) are model specific and cannot be shown in preview.

Product Formats

Use the following table to generate images based on your preferred size.

Product ID Product Format ID Type Name Width Height
1 1 images Stills White 1280 1280 960
1 11 images Stills 640 640 480
1 17 images Stills 640 PNG 640 480
1 18 images Stills White 640 640 480
2 2 images Color 1280 Angle 1 1280 960
2 3 images Color 1280 Angle 14 1280 960
2 4 images Color 1280 Angle 32 1280 960
2 5 images Color 640 Angle 1 640 480
2 6 images Color 640 Angle 1 PNG 640 480
2 7 images Color 640 Angle 14 640 480
2 8 images Color 640 Angle 14 PNG 640 480
2 9 images Color 320 Angle 14 320 240
2 10 images Color 640 Angle 32 640 480
2 12 images Color 640 Angle 32 PNG 640 480
2 33 images Color 320 Angle 1 320 240
2 34 images Color 320 Angle 32 320 240
2 35 images Color 480 Angle 1 480 360
2 36 images Color 480 Angle 14 480 360
2 37 images Color 480 Angle 32 480 360
6 14 images Exterior JPG Spin Frames 640 640 480
6 15 images Exterior PNG Spin Frames 640 640 480
6 22 videos Exterior Quicktime 320x240 36 Frame 320 240
7 16 images Splash 640x480 640 480
8 19 videos HD Clips 640 640 360
9 20 videos Signature 640 640 360
10 21 videos Editorials - 640x360 MPEG4 2.H64 codec 400Kb/s 640 360
11 23 videos Flyaround - 640x360 MPEG4 2.H64 codec 400Kb/s 640 360
13 24 videos Spins (5 seconds) - 640x480 MPEG4 2.H64 codec 200Kb/s 640 480
13 25 videos Spins (15 seconds) - 640x480 MPEG4 2.H64 codec 200Kb/s 640 480
13 26 videos Spins (90 seconds) - 640x480 MPEG4 2.H64 codec 400Kb/s 640 480
18 32 images Colorized 7 Frame Spin (1280x720) 1280 720

This table is to be used in conjunction with /vehicle endpoint.
Format:

/v1/{format}/vehicle/{vehicleID}?productID={productID}&productFormatIDs={productFormatID}&shotCode={shotCode}&api_key={apiKey}


Examples
https://api.fuelapi.com/v1/json/vehicle/25300?productID=1&productFormatIDs=1&shotCode=037&api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1

You can search for multiple product formats by comma separating them within the call:

https://api.fuelapi.com/v1/json/vehicle/25300?productID=1&productFormatIDs=1,11&shotCode=037&api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1

What's New

Move your inventory with better Images.

Starting at $199 per month, FUEL, powered by Evox Images, can instantly export professional quality images to your own dealer website or to popular portal sites like Cars.com, making your listings more accurate, more professional and more effective.

read more

Partners