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.

$ curl https://api.fuelapi.com/v1/json/makes/?year=2014&api_key=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"
                        },
                        ...
                     ]
                        

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 an invalid parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - Parameters were valid but the request failed.
404 Not Found - The requested resource 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/19100/?api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1

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

Still for this vehicle - Shot Code 046
https://api.fuelapi.com/v1/json/vehicle/19100/?api_key=daefd14b-9f2b-4968-9e4d-9d4bb4af01d1&productID=1&shotCode=046

Color images for this vehicle - Black
https://localapi.fuelapi.com/v1/json/vehicle/19100/?api_key=e0878ffa-a013-4b88-968e-9f75784ae3a5&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
037Driver's side profile with drivers side door open.
038Passenger's side view, sliding door open (vans only).
039Inside of driver's side open door, window open.
040Driver's side inside window controls.
041Drivers side profile, convertible top up (convertibles only).
042Front Drivers side wheel at profile.
043Drivers Side Headlight.
044Passenger Side Taillight.
045Drivers Side Door handle.
046Front angle view.
049Trunk open.
050Engine.
051Front seats from Drivers Side.
052Rear seats from Drivers Side.
0533rd row seat from Driver Side.
057Closeup of radio head unit
059Centered wide dash shot
061Front center divider.
062Speedometer/tachometer.
063Gas cap release.
064Courtesy lamps/ceiling controls.
065Seat Adjustment Controllers.
066Cup holders.
076Chrome tip exhaust pipe.
077Gas cap open.
081Sunroof/moonroof.
086Rear A/C controls.
087Gear shifter/center console.
088Passenger seat.
089Front angle medium view.
090Front angle view, low wide perspective.
111Driver position view of navigation system.
113System Controls.
115Hatchback & SUV rear angle.
116Front angle medium view.
117Overhead.
118Low/wide front.
119Low/wide rear.
120Low/wide front 5/8.
121Low/wide rear 5/8.
122Trunk props.
123Auxiliary jack props.
124Roof rack props.
125Convertible overhead (top up)
126Cup holder prop (primary).
127Cup holder prop (secondary).
128Cup holder prop (tertiary).
129Cup holder prop (quaternary).
130Glove box open.
132Driver’s side mirror, ¾ rear
133Driver’s side fog lamp.
134Driver’s side puddle lamp, illuminated
135Rear window wiper
136Rear hatch window open
137Step bars and running boards
138Rear manufacture badge/emblem
139Rear model badge/emblem
140Front center console with closed lid, from driver’s side looking down
141Zune and auxiliary jack
143Rear center console with closed lid from driver’s side looking down.
144Driver’s floor mat and pedals. Mid-seat level from outside looking in.
145Rear driver’s side floor mat. Mid-seat level from outside looking in.
147Key fob on driver’s seat.
148Centered wide dash shot – “night” shot.
149Rear storage bin
150Main power point.
151Second power point.
152Third power point.
153Fourth power point.
154Fifth power point.
155Sixth power point.
156Close up of Grill.
157Truck bed.
159Front passenger 3/4 w/ wheels turned.
160Fake Buck Shot – Interior from Passenger B pillar.
162Convertible Hero (high from passenger, looking down into interior).
163Interior Hero (driver’s side).
164Rear DVD.
165Second row side cup holder with coffee prop, or second row door cup holder with water bottle.
166Third Row center cup holder with coffee prop.
167Third Row side cup holder with coffee prop.
173Rear 3/4 angle view.
174Steering wheel/Center Console. 175 Center Console/Passenger Side. 176 Steering
175Center Console/Passenger Side.
176Steering Wheel Controls (Left Side)
177Steering Wheel Controls (Right Side)
178Keyless Ignition
179Ambient Lighting (Front Zone)
180Ambient Lighting (Middle Zone)
181Ambient Lighting (Rear Zone)
182Heated Seats Control
192Rear Back-up Camera

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

Partners