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

[
                    {
                        "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}

REQUIRED: vehicleID
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

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.

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

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