Dynamic Ads for Automotive - Catalogs and Feeds

To promote your automotive inventory on Facebook, you need to share information about your automotive with Facebook. You do this by creating a automotive catalog and then filling it with automotive details.

To create a catalog, you should connect a data feed or upload data to Facebook. The data should contain all the required fields for the vehicles that you want advertise, which are listed below.

Auto Feed Specification

You can have a single auto feed to represent all vehicles in your catalog; or multiple auto feeds where each feed represents a single dealership or region's vehicles.

Required fields include:

Type of FieldNameTypeDescriptionCan use in Creative?Can use as Product Set filter?

Generic

vehicle_id

String, max 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.

Generic

vin

String

VIN number of the vehicle

Generic

make

String

Make or brand of the vehicle, such as Ford

Y

Y

Generic

model

String

Model of the vehicle, such as Focus

Y

Y

Generic

year

int

Year the vehicle was launched in yyyy format, such as 2015

Y

Y

Generic

transmission

enum

Transmission type of the vehicle. Automatic or Manual

Y

Generic

body_style

enum

Body style of the vehicle: CONVERTIBLE, COUPE, HATCHBACK, MINIVAN, TRUCK, SUV, SEDAN,VAN, WAGON, CROSSOVER, or OTHER.

Y

Generic

fuel_type

enum

Diesel, Electric, Gasoline, Flex, Hybrid, or Other.

Y

Generic

drivetrain

enum

Drivetrain of the vehicle. Expected values are: 4X2, 4X4, AWD, FWD, RWD, or Other.

Y

Generic

description

String, max 5000

Short text describing the vehicle.

Y

Vehicle Specific Details

image

object

Image data for this vehicle. You can provide up to 20 images for the vehicle. Each image contains two fields: url and tag. You can have multiple tags associated with an image. You must provide at least one image. Each image can be up to 4MB in size.

Vehicle Specific Details

image:url, subset of image object above

String

The URL of the vehicle image. If you want to use carousel ads, provide a square 1:1 aspect ratio images which are 600x600px. To show single vehicle ads provide images with 1.91:1 aspect ratio image at 1200x630px

Vehicle Specific Details

mileage.value

int

Mileage of the vehicle in kms or miles, for used vehicles. Zero for new vehicles.

Y

Vehicle Specific Details

mileage.unit

String

Mileage units: MI or KM

Y

Vehicle Specific Details

url

url

Link to the external site where you can view destination page.

Vehicle Specific Details

title

String

Title of vehicle, such as "2017 Ford Focus 5DR HD SE"

Y

Vehicle Specific Details

price

String

Cost of vehicle and currency. Currency should follow ISO 4217 currency codes such as 13,999 USD.

Y

Y

Vehicle Specific Details

state_of_vehicle

enum

Whether the vehicle is new or used. Values supported are: New, Used, or CPO, meaning certified pre-owned.

Y

Vehicle Specific Details

exterior_color

String

Vehicle exterior color.

Y

Dealership Specific Details

address

object

A complete address for the dealership that must be resolvable to its location.

Y

Dealership Specific Details

In address, addr 1, or address 1

String

Street address of dealership, such as 675 El Camino Real.

Dealership Specific Details

In address, city

String

City dealership is in, such as Palo Alto.

Dealership Specific Details

In address, region

String

State, county, region or province for dealership, such as California.

Dealership Specific Details

In address, country

String

Country, such as United States

Dealership Specific Details

In address, longitude

float

The longitude of the dealership such as -122.148252.

Y

Optional fields include:

NameTypeDescription

chrome_id

int

Similar to autodata_id.

car_history_link

String

Link to a carfax report or other car history report

trim

String

Trim of the vehicle, such as "5DR HB SE"

tag (image tag)

String

A string that describes the image. There can be multiple tags associated with an image, such as "Exterior", "Interior", "StockImage"

interior_color

String

Vehicle interior color

condition

enum

Condition of the vehicle. Values expected are: excellent, good, fair, poor, or other.

sale_price

int

Sale price or special price.

video_ids

URL

Video IDs of the vehicle

availability

enum

Availability of the vehicle. Either available or not available. Note: We will not show vehicles that are not available in the ad

stock_number

String

A unique number, in addition to VIN and auto_id specified by manufacturer

dealer_id

String

Alphanumeric identifier of the dealer

dealer_name

String

Name of dealer

postal_code, in address object

String

Postal code, or zipcode of dealer

Example

curl \
-F 'name=catalog name' \
-F 'access_token=<ACCESS TOKEN>' \
-F 'vertical=vehicles' \
https://graph.facebook.com/<VERSION>/<BUSINESS ID>/product_catalogs

Learn more about Dynamic Ads, Product Catalog.

Create Data Feed

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.

For example, a TSV file with tab delimiters looks like this:

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 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 NEW 52.35 42.10

Here is an 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 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 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>
      <state_of_vehicle>NEW</state_of_vehicle>
      <dealer_id>ABC1234</dealer_id>
    </listing>
</listings>

You can have one or the other kind of feed: * A single vehicle feed to represent all vehicles in your catalog * Multiple vehicle feeds where each feed represents a single dealership or region's vehicles

Filter Vehicle Catalog to Vehicle Sets

Reference Docs

A vehicle set is a subset of your catalog. To set up Dynamic Ads for Automotive, you need to create at least vehicle set.

Vehicle sets are defined by filters that are applied to the Vehicle catalog. For example, you can create a vehicle set with all vehicles with a year later than 2015. Note: You can also create a vehicle set without any filters. In that case, the vehicle set contains all vehicles in your catalog.

Example: Create a vehicle set containing all the vehicles that manufactured in 2016

use FacebookAds\Object\ProductSet;
use FacebookAds\Object\Fields\ProductSetFields;

$vehicle_set = new ProductSet(null, <PRODUCT_CATALOG_ID>);

$vehicle_set->setData(array(
  ProductSetFields::NAME => 'Test Vehicle Set',
  ProductSetFields::FILTER => array(
    'year' => array(
      'eq' => 2016,
    ),
  ),
));

$ vehicle_set->create();

The filter parameter is made up of the following operators and data:

OperatorsThe type of filter

i_contains

Contains substring. Operator is case insensitive.

i_not_contains

Does not contain substring. Operator is case insensitive.

contains

Contains substring. Operator is case insensitive.

not_contains

Does not contain substring. Operator is case insensitive.

eq

Equal to. Operator is case insensitive.

neq

Not equal to. Operator is case insensitive.

lt

Less than. For numeric fields only.

lte

Less than or equal to. For numeric fields only.

gt

Greater than. For numeric fields only.

gte

Greater than or equal to. For numeric fields only.

Available Vehicle Fields for Product Set Filtering

FieldDescription

make

Make or brand of the vehicle.

model

Model of the vehicle.

year

Year the vehicle was launched.

transmission

Transmission type of the vehicle.

body_style

Body style of the vehicle.

fuel_type

Diesel, Electric, Gasoline, Flex, Hybrid or Other.

drivetrain

Drive train of the vehicle.

price

Cost of vehicle and currency.

state_of_vehicle

Whether the vehicle is new or used.

exterior_color

Vehicle exterior color.

address

A complete address for the dealership that must be resolvable to its location.

Schedule Uploads

You should schedule feed uploads to automatically push the latest vehicle inventory data to Facebook instead of uploading refreshed files manually.

To do this, make a POST request to product_feeds from the /{product_catalog_id}/product_feeds.

To add a schedule to the feed, provide schedule in the POST request.