Marketing API Version

Dynamic Ads for Flights - Catalogs & Feeds

To promote your flight inventory on Facebook, you have to share information about your flights with Facebook. You do this by creating a flight catalog and then filling it with flight routes. There are three ways to fill your catalog and keep it up to date.

  1. Upload CSV or XML files for 'flight feeds' with flight inventory
  2. Use event activity to automatically fill your catalog
  3. Combine a flight feed with automatically generated flights

You can create and manage your flight catalogs in your Catalog Manager. If you want to use the API to manage your catalog, take the following steps:

  1. Create a flight catalog
  2. Upload your feed to Facebook
  3. Create product sets out of your flight catalog
  4. Associate the catalog to your event sources

Flight Feed - Uploading your flights to Facebook

A flight feed is a file with your flight inventory. Every line or item in the file represents a single route. You can use one or more flight feeds, as long as all feeds together contain your full flight inventory.

Supported Flight Feed Formats

File FormatSample & Description

CSV

  1. The first row must list the chosen field names in the order the values will be given. Subsequent rows then supply the corresponding values for each flight.
  2. Fields containing whitespace or commas should be enclosed in "double quotes".
  3. 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, such as image[0].url, image[0].tag[0], image[0].tag[1]. Both conventions can be used interchangeably in the same file.

XML

  1. A root <listings> XML node encloses a set of <listing> nodes, each of which represents a flight.
  2. The file must begin with a valid <?xml declaration tag.

The feed parser automatically detects UTF8, UTF16 or UTF32 text-encodings, and defaults to to LATIN1 if it encounters an unexpected byte sequences. You can provide text in field values in any language, however field names must be given exactly as below, in English.

Flight Feed Fields

Field Name and TypeDescription

origin_airport

type: string

Required.

The IATA code for the origin. Supports airport and city IATA code. Use IATA Code Search to validate your IATA codes.

Example: SFO

destination_airport

type: string

Required.

The IATA code for the destination. Supports airport and city IATA code. Use IATA Code Search to validate your IATA codes.

Example: JFK

image

type: object

Required.

Max items: 20

Image data for this flight. You can provide up to 20 images for the flight. 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.

See Image Object Parameters

description

type: string

Required.

Max size: 5000

A short paragraph describing the route.

url

type: string

Required only if you do not specify a deep link on ad level. You can use the Deep Link field in Ads Manager, or template_url_spec in the API).

Link to the external site where you can view the flight. If a deep link is specified on ad level, that will take precedence.

origin_city

type: string

The name of the origin city.

Example: San Francisco

destination_city

type: string

The name of the destination city.

Example: New York

price

type: string

Price of the flight. You must specify the value with currency.

Example: 99.99 USD

applink

type: element

Deep link straight to the flight details page in your mobile app using App Links. You can specify deep links (in order of precedence, highest to lowest):

  1. on ad level using template_url_spec
  2. here in the feed using an Applink Object
  3. by adding App Link meta tags to your website.

one_way_price

type: element

One-way price of the flight. You must specify the value with currency.

Example: 99.99 USD

Image Object Parameters

Field Name and TypeDescription

url

type: string

Required.

The URL of the flight image. Provide an image with a 1.91:1 aspect ratio of at least 1200x630px. For carousel ads, provide square 1:1 ratio images of at least 600x600px.

tag

type: string

A string that represents what's in the image. There can be multiple tags associated with an image.

Examples:

  • Fitness Center
  • Swimming Pool

If you have separate apps for iPhone and iPad, specify iPhone and iPad specific information. Otherwise specify only iOS information.

Field Name and TypeDescription

ios_url

type: string

A custom scheme for the iOS app.

Example: example-ios://electronic

ios_app_store_id

type: string

The app ID for the App Store.

Example: 1234

ios_app_name

type: string

The name of the app (suitable for display).

Example: Electronic Example iOS

iphone_url

type: string

A custom scheme for the iPhone app.

Example: example-iphone://electronic

iphone_app_store_id

type: string

The app ID for the App Store.

Example: 5678

iphone_app_name

type:string

The name of the app (suitable for display).

Example: Electronic Example iPhone

ipad_url

type: string

A custom scheme for the iPhone app.

Example: example-ipad://electronic

ipad_app_store_id

type: string

The app ID for the App Store.

Example: 9010

ipad_app_name

type: string

The name of the app (suitable for display).

Example: Electronic Example iPad

android_url

type: string

A custom scheme for the Android app.

Example: example-android://electronic

android_package

type: string

A fully-qualified package name for intent generation.

Exammple: com.electronic

android_class

type: string

A fully-qualified Activity class name for intent generation.

Example: com.electronic.Example

android_app_name

type: string

The name of the app (suitable for display).

Example: Electronic Example Android

Autogenerate flights - Add routes to catalog automatically using event activity

Facebook can automatically add routes to your catalog based on pixel and app event activity. Every time an event is received with a route that does not yet exist in the catalog, it can be added automatically. This allows to you use Dynamic Ads for Flights for all your flights without having to deal with flight feeds.

To enable this, make a POST request to your flight catalog, and set generate_items_from_events to true.

curl \
-F 'flight_catalog_settings={'generate_items_from_events'=1} \
-F 'access_token=<ACCESS_TOKEN>>' \
https://graph.facebook.com/<VERSION>/<CATALOG_ID>

Routes that are added automatically don't have an image (to display in the ad). Therefore, you will have to provide a generic image to use for all autogenerated routes.

curl \
-F 'fallback_image_url=http://example.com/some.image_1.jpg' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/<CATALOG_ID>

As soon as your catalog is associated to a pixel and/or app, and receiving Dynamic Ads for Flights events, your catalog will populate. You can verify this by querying the catalog.

curl \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/flights

Combined - use flight feeds with automatically generated flights

You can combine uploading a flight feed with autogenerated routes. Combining these options allows you to leverage Dynamic Ads for Flights for all your flights, while providing custom images for your most important routes using a flight feed.

To do so, just combine the steps uploading a flight feed with automatically filling your catalog.

The following sections are only relevant if you want to manage your catalogs using this API.

Create a Flight Catalog using the API

A flight catalog is a container for your flight inventory. To use the catalog API, make sure you have the appropriate Marketing API Access Level and that you have accepted the Terms of Service by creating your first catalog through Business Manager.

To create a flight catalog for Dynamic Ads for Flights, set vertical to flights:

curl -X POST \ -F 'name=Test Flight Catalog' \ -F 'vertical=flights' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v2.10/{business-id}/product_catalogs
const adsSdk = require('facebook-nodejs-ads-sdk'); const Business = adsSdk.Business; const ProductCatalog = adsSdk.ProductCatalog; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const fields = [ ]; const params = { 'name' : 'Test Flight Catalog', 'vertical' : 'flights', }; (new Business(id)).createProductCatalog( fields, params ) .then((result) => { product_catalogs_id = result.id; console.log(product_catalogs_id); }) .catch((error) => { console.log(error); });
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Business; use FacebookAds\Object\ProductCatalog; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Test Flight Catalog', 'vertical' => 'flights', ); echo json_encode((new Business($id))->createProductCatalog( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.business import Business from facebookads.adobjects.productcatalog import ProductCatalog from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Test Flight Catalog', 'vertical': 'flights', } print Business(id).create_product_catalog( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Business(id, context).createProductCatalog() .setName(\"Test Flight Catalog\") .setVertical(ProductCatalog.EnumVertical.VALUE_FLIGHTS) .execute(); } }
access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end business = FacebookAds::Business.get(id) business.product_catalogs.create({ name: 'Test Flight Catalog', vertical: 'flights', })

Upload your flight feeds through the API

Once you have created the catalog, you have to upload your flight feed(s) to Facebook. Use the API to create a feed object for every feed you want to upload. We support scheduled and direct uploads.

For scheduled uploads, specify a schedule when you create the feed. For non scheduled uploads, don't specify a schedule.

use FacebookAds\Object\ProductFeed;
use FacebookAds\Object\Fields\ProductFeedFields;
use FacebookAds\Object\Fields\ProductFeedScheduleFields;

$product_feed = new ProductFeed(null, <PRODUCT_CATALOG_ID>);

$product_feed->setData(array(
  ProductFeedFields::NAME => 'Test Feed',
  ProductFeedFields::SCHEDULE => array(
    ProductFeedScheduleFields::INTERVAL => 'DAILY',
    ProductFeedScheduleFields::URL =>'http://www.example.com/sample_feed.tsv',
    ProductFeedScheduleFields::HOUR => 22,
  ),
));

$product_feed->create();
from facebookads.adobjects.productfeed import ProductFeed

product_feed = ProductFeed(parent_id=<PRODUCT_CATALOG_ID>)

product_feed[ProductFeed.Field.name] = 'Test Feed'
product_feed[ProductFeed.Field.schedule] = {
    'interval': 'DAILY',
    'url': 'http://www.example.com/sample_feed.tsv',
    'hour': 22,
}

product_feed.remote_create()
ProductFeed productFeed = new ProductCatalog(<PRODUCT_CATALOG_ID>, context).createProductFeed()
  .setName("Test Feed")
  .setSchedule("{\"interval\":\"DAILY\",\"url\":\"http://www.example.com/sample_feed.tsv\",\"hour\":\"22\"}")
  .execute();
String product_feed_id = productFeed.getId();
curl \
  -F 'name=Test Feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_feed.tsv", 
    "hour": 22 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PRODUCT_CATALOG_ID>/product_feeds

In either case, the response is:

{ "id" : <PRODUCT_FEED_ID> }

Once you have created the feed (with or without schedule), you can do a one time upload of your feed using the PRODUCT_FEED_ID:

curl \
-F "url=http://www.example.com/sample_feed.xml" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_FEED_ID>/uploads

Filter Flight Catalog to Flight Sets

Reference Docs

A flight set is a subset of your catalog. To setup Dynamic Ads for Flights, you need a flight set. Therefore, you have to create at least one.

Flight sets are defined by filters that are applied to the flight catalog. For example, you can create a flight set with all routes that depart from London. Do note you can also create a flight set without any filters. In that case, the flight set will contain all flights in your catalog.

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

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

$flight_set->setData(array(
  ProductSetFields::NAME => 'Test Flight Set',
  ProductSetFields::FILTER => array(
    'origin_airport' => array(
      'eq' => 'LHR',
    ),
  ),
));

$flight_set->create();
from facebookads.adobjects.productset import ProductSet

flight_set = ProductSet(None, <PRODUCT_CATALOG_ID>)

flight_set[ProductSet.Field.name] = 'Test Flights Set'
flight_set[ProductSet.Field.filter] = {
    'origin_airport': {
        'eq': 'SFO',
    },
}

flight_set.remote_create()
curl \
  -F 'name=Test Flight Set' \
  -F 'filter={"origin_airport":{"eq":"LHR"}}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PRODUCT_CATALOG_ID>/product_sets

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.

DataThe data being filtered

origin_airport

The IATA code for the origin.

destination_airport

The IATA code for the destination.

price

Price of the flight. The price is in cents.

description

A short paragraph describing the route.

Associate the catalog to your event sources

To map the data from your event sources (your pixels and app events) to your catalog, every catalog must be associated with these event sources. You can do this by visiting your business manager's catalog page and clicking the 'Associate Sources' button. Make sure to select the app and pixel that are receiving the travel events. Alternatively, you can use the API.

use FacebookAds\Object\ProductCatalog;

$product_catalog = new ProductCatalog(<PRODUCT_CATALOG_ID>);
$product_catalog->createExternalEventSource(array(), array(
  'external_event_sources' => array(
    <PIXEL_ID>,
    <APP_ID>,
  ),
));
from facebookads.adobjects.productcatalog import ProductCatalog

product_catalog = ProductCatalog(<PRODUCT_CATALOG_ID>)
product_catalog.add_external_event_sources([
    <PIXEL_ID>,
    <APP_ID>,
])
curl \
  -F 'external_event_sources=["<PIXEL_ID>","<APP_ID>"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PRODUCT_CATALOG_ID>/external_event_sources

When making the API call, specify the following parameters:

Parameter Name & TypeDescription

external_event_sources

type: int[]

A list of Pixel and App IDs to associate with the catalog.