Reference

Use this guide as a reference of supported feed formats and fields to create automotive ads.

All enum fields are case-insensitive.

Automotive Inventory Ads - Supported Feed Formats

Provide your feed in the correct format: CSV, TSV, or XML. Once you create the feed file, you should host it at a URL for regular scheduled updates.

Feed Format Description & Guidelines Sample Feed

Feed Format	Description & Guidelines	Sample Feed
CSV	Comma-separated value. The first row specifies the column header. Subsequent rows supply the corresponding values for each route. Fields containing whitespace or commas should be enclosed in "double quotes". A double quote inside a double-quoted field must be escaped with two consecutive double quotes. Nested or multi-value fields, such as image, can be represented using JSON-encoded values or by a set of "flattened" plain-text columns labeled using JSON-path syntax. Example: `(image[0].url`, `image[0].tag[0]`, `image[0].tag[1])` Both conventions can be used interchangeably in the same file. See Feed CSV/TSV example, Address CSV/TSV example.	Download > Right-click > Save Link As
TSV	Tab-separated value. See guidelines for CSV. See Feed CSV/TSV example, Address CSV/TSV example.	Download > Right-click > Save Link As
XML	Format typically generated by automated feed provider systems or web servers. A set of item XML nodes represents a product list and must begin with the `<?xml` declaration tag. See Feed XML example.	Download > Right-click > Save Link As

CSV

Comma-separated value.

The first row specifies the column header. Subsequent rows supply the corresponding values for each route.
Fields containing whitespace or commas should be enclosed in "double quotes". A double quote inside a double-quoted field must be escaped with two consecutive double quotes.
Nested or multi-value fields, such as image, can be represented using JSON-encoded values or by a set of "flattened" plain-text columns labeled using JSON-path syntax. Example: (image[0].url, image[0].tag[0], image[0].tag[1])
Both conventions can be used interchangeably in the same file.

See Feed CSV/TSV example, Address CSV/TSV example.

Download > Right-click > Save Link As

TSV

Tab-separated value. See guidelines for CSV.

See Feed CSV/TSV example, Address CSV/TSV example.

Download > Right-click > Save Link As

XML

Format typically generated by automated feed provider systems or web servers. A set of item XML nodes represents a product list and must begin with the <?xml declaration tag.

See Feed XML example.

Download > Right-click > Save Link As

Example - TSV file with tab delimiters

vehicle_id title description url make model year mileage.value mileage.unit image[0].url image[0].tag[0] transmission fuel_type body_style drivetrain vin condition price address exterior_color sale_price availability date_first_on_lot state_of_vehicle latitude longitude i2 2017 Ford Fusion SE Ford Certified and 6-Speed Automatic. Turbocharged! Gasoline! http://www.example.com/test Ford Fusion 2017 1500 KM http://www.facebook.com/teapic.jpg Gym AUTOMATIC GASOLINE SEDAN FWD 1FADP5AU6DL536022 EXCELLENT 18000 USD {addr1: '550 Auto Center Dr', city: 'Watsonville', region: 'CA', postal_code: '96075', country: 'US'} white 16000 USD AVAILABLE 2018-02-21  NEW 52.35 42.10

Example — Feed with images as an array

auto_listing_id title description url make model year mileage.value mileage.unit image transmission fuel_type body_style drivetrain vin condition price address exterior_color sale_price availability date_first_on_lot state_of_vehicle latitude longitude
"i2" 2017 Ford Fusion SE Ford Certified and 6-Speed Automatic. Turbocharged! Gasoline! http://www.example.com/test Ford Fusion 2017 1500 KM "[{""url"":""https://images.trvl-media.com/hotels/3000000/2260000/2250400/2250336/2250336_1_y.jpg""}]" AUTOMATIC GASOLINE SEDAN FWD 1FADP5AU6DL536022 EXCELLENT 18000 USD {addr1: '550 Auto Center Dr', city: 'Watsonville', region: 'CA', postal_code: '96075', country: 'US'} white 16000 USD AVAILABLE 2018-09-15 NEW 52.35 42.10

This sample feed is as XML:

<?xml version="1.0" encoding="UTF-8"?>
<listings>
    <title>Vehicles Feed</title>
    <link rel="self" href="http://www.example.com"/>
    <listing>
      <vehicle_id>SED1234</vehicle_id>
      <title>2017 Ford Fusion SE</title>
      <description>Ford Certified and 6-Speed Automatic. Turbocharged! Gasoline!</description>
      <url>http://www.example.com/test</url>
      <make>Ford</make>
      <image>
        <url>http://example.com/some.image_1.jpg</url>
        <tag>Exterior</tag>
      </image>
      <model>Fusion</model>
      <year>2017</year>
      <mileage>
        <value>10</value>
        <unit>MI</unit>
      </mileage>
      <drivetrain>FWD</drivetrain>
      <vin>1FADP5AU6DL536022</vin>
      <body_style>SEDAN</body_style>
      <fuel_type>GASOLINE</fuel_type>
      <transmission>AUTOMATIC</transmission>
      <condition>EXCELLENT</condition>
      <price>18000 USD</price>
      <address format="simple">
          <component name="addr1">550 Auto Center Dr</component>
          <component name="city">Watsonville</component>
          <component name="region">CA</component>
          <component name="postal_code">95076</component>
          <component name="country">US</component>
      </address>
      <latitude>52.35</latitude>
      <longitude>42.10</longitude>
      <exterior_color>white</exterior_color>
      <sale_price>16000 USD</sale_price>
      <availability>AVAILABLE</availability>
      <date_first_on_lot>2018-02-21</date_first_on_lot>
      <state_of_vehicle>NEW</state_of_vehicle>
      <dealer_id>ABC1234</dealer_id>
    </listing>
</listings>

Example - Feed CSV/TSV

"vehicle_id","vehicle_registration_plate","vin","make","model","year","transmission","body_style","fuel_type","drivetrain","description","image[0].url", "image[1].url","image[2].url","mileage.value","mileage.unit","url","title","price","state_of_vehicle","exterior_color","address","latitude","longitude","trim","interior_colour","dealer_id","dealer_name","postal_code","dealer_phone","fb_page_id","dealer_communication_channel","dealer_privacy_policy_url"
"56345636","AB12CDE","YV1DZ8256F2693747","Volvo","XC60","2014","AUTOMATIC","OTHER","DIESEL","OTHER","Volvo XC60 2.4 TD D5 R-Design Lux Geartronic 5dr (Nav)","http://website.com/images/stock/car1.jpg","http://website.com/images/stock/car2.jpg","http://website.com/images/stock/car3.jpg","12950","MI","http://www.dealership.co.uk","Volvo XC60 2.4 TD D5 R-Design Lux Geartronic 5dr (Nav)","22495.00 GBP","Used","White","{""addr1"":""Sample Road"",""city"":""London"",""region"":""Greater London"",""postal_code"":""SW31 3EW"",""country"":""United Kingdom""}","52.7445867","-2.7337375","2.4 TD D5 R-Design Lux Geartronic 5dr (Nav)","Black","436456435347346","Dealer Group","SSW31 3EW","","3562564376375","CHAT","https://www.dealership.co.uk/site/privacy-and-legal/"

Example - Address CSV/TSV

"{addr1: '1 Hacker Way', city: 'Menlo Park', region: 'CA', postal_code: '94025', country: 'US'}"

Example - Feed XML

<?xml version="1.0" encoding="UTF-8"?>
<listings>
  <title>Sample Vehicles Feed</title>
  <link rel="self" href="https://www.example.com/dealers/cars/1234/?r=vddn" />
  <listing>
    <vehicle_id>3456553</vehicle_id>
    <title>Ford B-MAX ZETEC</title>
    <description>Adjustable Steering Column, Adjustable Steering Wheel, Air Bags, Air Conditioning, Alloy Wheels, Anti Lock Brakes, Bluetooth Preparation (Phone), CD Player, CD Radio, Driver Airbag, Electric & Heated Door Mirrors, Electric Windows, Electronic Stability Programme (ESP), Front Electric Windows, Front Fog Lights, Height Adjustable Drivers Seat, Passenger Airbag, Power Assisted Steering (PAS), Power Fold &amp; Heated DoorMirrors, Rear Parking Sensor, Remote Boot Release, Remote Central Locking, Solid Paint,LOW MILEAGE WITH A FULL FORD HISTORY, SUPPLIED FROM US,</description>
    <url>https://www.example.com/car-1234>
    <make>Ford</make>
    <image>
      <url>https://www.example.com/1234/image_1.jpg</url>
    </image>
    <image>
      <url>https://www.example.com/1234/image_2.jpg</url>
    </image>
    <image>
      <url>https://www.example.com/1234/image_3.jpg</url>
    </image>
    <model>B-MAX</model>
    <year>2015</year>
    <mileage>
      <value>15617</value>
      <unit>MI</unit>
    </mileage>
    <drivetrain>Other</drivetrain>
    <vin>1A2BCDEF3GH456789</vin>
    <body_style>OTHER</body_style>
    <fuel_type>Gasoline</fuel_type>
    <transmission>Manual</transmission>
    <price>9490 GBP</price>
    <address format="simple">
      <component name="addr1">Sample Road</component>
      <component name="city">Carland</component>
      <component name="region">North Test</component>
      <component name="country">United States of America</component>
      <component name="postal_code">12345</component>
    </address>
    <latitude>37.484419</latitude>
    <longitude>-122.148406</longitude>
    <exterior_color>White</exterior_color>
    <state_of_vehicle>Used</state_of_vehicle>
    <dealer_id>453356</dealer_id>
    <vehicle_registration_plate>AB12CD</vehicle_registration_plate>
    <fb_page_id>5636367576574</fb_page_id>
    <dealer_communication_channel>LEAD_FORM</dealer_communication_channel>
    <dealer_privacy_policy_url>https://www.example.com/privacy/</dealer_privacy_policy_url>
  </listing>
</listings>

Automotive Inventory Ads - Supported Fields - Vehicle

The following supported fields are designed for items you add to your product catalog.

For localized catalogs, see supported fields for vehicle.

Name	Description	Use in Creative	Use as a product set filter
`fb_page_id` type: int	Required for Marketplace; NA for dynamic ads. Facebook page ID of the partner or dealership. *Your catalog must be whitelisted by your Facebook representative before you can send your page IDs. The page must be whitelisted using the Business Manager before* can be ingested**. See Managing Permissions.	N	N
`vehicle_id` type: string	Required for Marketplace & dynamic ads. Max characters: 100 Unique ID for item. Can be a variant for a vehicle. If there are multiple instances of the same ID, we ignore all instances. You can also use the VIN for both `vehicle_id` and `vin`. Example: `1FADP5AU6DL536022`	Y	Y
`title` type: string	Required for Marketplace & dynamic ads. Max characters: 500. Full name of vehicle. This is relevant and specific to each vehicle and it should contain what is set in `year`, `make`, `model`, `trim`. Example: `SE Ford Certified and 6-Speed Automatic`	Y	Y
`description` type: string	Required for Marketplace & dynamic ads. Max characters: 5000 Short text describing the vehicle. Don't include promotional text or any links. Don't enter text in all capital letters. Use line breaks to format your description. Example: `Used 2017 Volvo XC90 in great condition, available now.`	Y	N
`url` type: url	Required for dynamic ads; Optional for Marketplace. Link to the external site where you can view the vehicle listing.	Y	N
`make` type: string	Required for Marketplace & dynamic ads. Make or brand of the vehicle. Example: `Ford`	Y	Y
`model` type: string	Required for Marketplace & dynamic ads. Model of the vehicle. Example: `Fusion`	Y	Y
`year` type: int	Required for Marketplace & dynamic ads. Year the vehicle was launched in `yyyy` format. Example: `2015`	Y	Y
`mileage.value` type: int	Required for Marketplace & dynamic ads. For used vehicles, current mileage of the vehicle in kilometers (`kms`) or miles (`MI`). For new vehicles, use zero (`0`). For Marketplace, vehicles must have over 500 miles/kms. Example: '1500'	Y	Y
`mileage.unit` type: string	Required for Marketplace & dynamic ads. Mileage units: `MI` (miles) or `KM` (kilometers)	Y	N
`image[0].url` type: string	Required for Marketplace & dynamic ads. Max items: 20 URL of the vehicle image. If you have more than one vehicle image, follow this naming convention: `image[1].url`, `image[2].url`, and so on. You must provide at least one image. Each image can be up to 4 MB in size. For Marketplace, a 2-image minimum is required. To use carousel ads — Provide a square 1:1 aspect ratio images (600x600px). To show single vehicle ads — Provide images with 1.91:1 aspect ratio image (1200x630px). Learn more about Marketplace Best Practices for images.	N	N
`transmission` type: enum	Optional for Marketplace & dynamic ads. Transmission type of the vehicle: `Automatic` or `Manual`.	N	Y
`body_style` type: enum	Required for Marketplace & dynamic ads. Body style of the vehicle: `CONVERTIBLE`, `COUPE`, `HATCHBACK`, `MINIVAN`, `TRUCK`, `SUV`, `SEDAN`, `VAN`, `WAGON`, `CROSSOVER`, `SMALL_CAR`, or `OTHER`.	Y	Y
`drivetrain` type: enum	Optional for Marketplace & and dynamic ads. Vehicle drivetrain. Supported values: `4X2`, `4X4`, `AWD`, `FWD`, `RWD`, `Other`.	N	Y
`vin` type: string	Required for dynamic ads & Marketplace, some countries. Max characters: 17 Vehicle ID number (VIN) of the vehicle. You can also use the VIN for both `vehicle_id` and `vin`. Note: The VIN must be exactly 17 characters and it isn't required for pre-1983 vehicles. Boats have less digits and some vehicles (such as trailers) don't need VINs. Example: `1FADP5AU6DL536022`	Y	Y
`price` type: string	Required for Marketplace & dynamic ads. Cost and currency of the vehicle. Format the price as the cost, followed by the ISO currency code, with a space between cost and currency. For Marketplace - new vehicles only, see Additional Fields for Specific Countries Example: `18000 USD`, `32000 USD`	Y	Y
`exterior_color` type: string	Required for Marketplace & dynamic ads. Vehicle color. Example: `Black`, `White`, `Blue`, `Red`	Y	Y
`state_of_vehicle` type: enum	Required for Marketplace & dynamic ads. Current state of the vehicle. Supported values: `New`, `Used`, or `CPO` (certified pre-owned).	N	Y
`fuel_type` type: enum	Optional for Marketplace & and dynamic ads. Vehicle fuel type. Supported values: `DIESEL`, `ELECTRIC`, `FLEX`, `GASOLINE`, `HYBRID`, `OTHER`.	N	Y
`image[0].tag[0]` type: string	Optional for Marketplace & dynamic ads. Max items: 20 Tag appended to the image that shows what's in the image. There can be multiple tags associated with an image. Follow this naming convention: `image[0].tag[0], image[0].tag[1]` .... `image[1].tag[0], image[1].tag[1]` .... Example: `Exterior`, `Interior`, `StockImage`	N	Y
`tag` (image tag) type: string	Optional for Marketplace & and dynamic ads. String that describes the image. There can be multiple tags associated with an image. Example: `Exterior`, `Interior`, `StockImage`	Y	N
`chrome_id` type: int	Optional for Marketplace; NA for dynamic ads. Similar to `autodata_id`.	N	N
`condition` type: enum	Optional for Marketplace & and dynamic ads. Condition of the vehicle. Supported values: `EXCELLENT`, `GOOD`, `FAIR`, `POOR`, or `OTHER`.	N	Y
`sale_price` type: integer	Optional for Marketplace & dynamic ads. Sale price or special price. Format the price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: `16000 USD`	Y	Y
`availability` type: enum	Optional for Marketplace & dynamic ads. Vehicle availability: `available` or `not available`. We don't show vehicles that are unavailable in the ad.	N	Y
`vehicle_type` type: string	Optional for dynamic ads amp; for Marketplace. Type of vehicle. Expected values: `car_truck` (default if not supplied), `boat`, `commercial`, `motorcycle`, `powersport`, `rv_camper`, `trailer`, or `other`.	N	Y
`trim` type: string	Optional for dynamic ads and Marketplace. Max characters: 50 Trim of the vehicle. Example: `5DR HB SE`	Y	Y
`interior_color` type: string	Optional for dynamic ads and Marketplace. Max characters: 50 Vehicle interior color.	N	Y
`date_first_on_lot` type: string	Optional for dynamic ads and Marketplace. Date when this vehicle first arrived at the dealer lot. Used to indicate inventory age. Use `yyyy-mm-dd` format. Example: `2018-09-05`	N	Y

Automotive Inventory Ads - Supported Fields - Dealership

Name	Description	Use in Creative	Use as a product set filter
`address`, `addr1`, `address 1` type: string	Required for Marketplace & dynamic ads. Complete dealership physical address, formatted as: `{addr 1: [STREET ADDRESS], city: [CITY], region: [STATE, COUNTY, REGION OR PROVINCE], country: [COUNTRY]`. The postal code is optional. Example: `{addr1: '550 Auto Center Dr', city: 'Watsonville', region: 'CA', postal_code: '96075', country: 'US'}`	N	N
`address.city` type: string	Required for Marketplace. City where the dealership is located. Example: `Palo Alto`	Y	Y
`address.region` type: string	Required for Marketplace. State, county, region, or province where the dealership is located. Example: `California`	Y	Y
`addr.country` type: string	Required for Marketplace. Country where the dealership is located. Example: `United States`	N	Y
`latitude` type: float	Required for dynamic ads & Marketplace. Latitude of the dealership location. Example: `37.484100`	N	N
`longitude` type: float	Required for dynamic ads amp; Marketplace. Longitude of the dealership location. Example: `-122.148252`	N	N
`addr.postal_code` type: string	Optional for Marketplace. Postal code for vehicle (outside the U.S. or zip code within the U.S.). Example: `75008` (Paris, France) or `94025` (Menlo Park)	N	N
`dealer_id` type: string	Optional for dynamic ads. Required for Marketplace. Max characters: 100 Alphanumeric ID of the dealership.	Y	Y
`dealer_name` type: string	Optional for dynamic ads. Required for Marketplace. Max characters: 100 Name of dealership.	Y	Y
`dealer_phone` type: string	Optional for dynamic ads. Required for Marketplace. Phone number of dealership. Must be a valid phone number format and must include the country code. Required to display the Call button on a Marketplace-based listing. Example: `+1 3603453333`, `001 (360)345-3333`	N	N
`dealer_communication_channel` type: enum	Optional for dynamic ads. Required for Marketplace. Method with which the dealer will be contacted by the user. Available values: `CHAT` or `LEAD_FORM`. `LEAD_FORM` is subject to regional availability. When unavailable, every listing is forced to `CHAT`, regardless of the value provided.	N	N
`dealer_privacy_policy_url` type: url	Optional for dynamic ads. Required for Marketplace. Link to the privacy URL of the dealer listing the vehicle. This should match the dealer of the Facebook page ID (`fb_page_id`).	N	N
`stock_number` type: string	Optional for dynamic ads & Marketplace. Dealership's own designation of the car on their lot. The stock number is a way for the dealer to inventory specific vehicles. Example: `N8990`	Y	Y
`custom_label_0` type: string	Optional for Marketplace & dynamic ads. Max character limit: 100 Additional information about the vehicle you want to include.	Y	Y
`custom_label_1` type: string	Optional for Marketplace & dynamic ads. Max character limit: 100 Additional information about the vehicle you want to include.	Y	Y
`custom_label_2` type: string	Optional for Marketplace & dynamic ads. Max character limit: 100 Additional information about the vehicle you want to include.	Y	Y