Face Book Ads API

Facebook Ads API Documentation October 2009

Facebook Ads API (Beta) Documentation

2009

(Beta)

Introduction At Facebook, we’re constantly working to match advertisers with users who are interested in their products and services. We know that you see a better response from yourwhen you tailor ad creative and targeting criteria to specific sets of users, so we’ve created theAdvertising Application Programming Interface (often complex ad campaigns The Facebook Ads API (currently in beta testing) directly with the Facebook Ads platform. Ads API to automatically create, mto update your campaigns based on their performance without relying on manual updates.We’re excited to invite you to beta The Ads API is part of the Facebook Developer Platform. For general information about the developer platform, please visit the Facebook Developerhttp://developers.facebook.com. This document describes the advertisingDeveloper Platform which you can use to programmatically create, edit, manage, and get reporting on your Facebook Ads. Follow these steps to set up a Facebook application, which you need Facebook Ads API.

1. Log in to the account you’ll use to develop the applicationFacebook account, not an advertising

2. Go to http://www.facebook.com/developers/3. Click “Set Up New Application” 4. Enter an application name5. Send the resulting “API Key” value to

a support team member will activate the key for use with the Ads API. The key looks something like this: f43418a3fc929e2bfa3d8dcc549351d2. We do not need your application secret.

6. Add any other users who need to 7. Click “Save Changes” to finish configuring the application.

The API Test Console (http://developers.facebook.com/tools.phpmethods listed in this document when called with an application / account ID that has access to the Ads API. Please note that many API calls use JSONConsole will also require the parameters to be JJSON requests and results section under Documentation Nomenclature below and API calls for specific details.

Document Nomenclature

Ads API Documentation (Beta) |

At Facebook, we’re constantly working to match advertisers with users who are interested in We know that you see a better response from your

when you tailor ad creative and targeting criteria to specific sets of users, so we’ve created theAdvertising Application Programming Interface (Ads API) to help you manage your

(currently in beta testing) enables you to build applications that interactdirectly with the Facebook Ads platform. You can build an application that uses theAds API to automatically create, monitor, and update your advertising campaigns,

our campaigns based on their performance without relying on manual updates.beta test these tools.

API is part of the Facebook Developer Platform. For general information about the platform, please visit the Facebook Developers Website at

.

he advertising-specific functionality that has been added to the which you can use to programmatically create, edit, manage, and get

.

Follow these steps to set up a Facebook application, which you need in order to use the

you’ll use to develop the application. This must be a real n advertising-only “gray account.”

http://www.facebook.com/developers/ pplication”

an application name, agree to the Terms of Service, then click “Save Changes.”Send the resulting “API Key” value to [email protected],

will activate the key for use with the Ads API. The key looks f43418a3fc929e2bfa3d8dcc549351d2. We do not need your

Add any other users who need to access this application in the “Developers” list.Click “Save Changes” to finish configuring the application.

http://developers.facebook.com/tools.php) allows you to tlisted in this document when called with an application / account ID that has access to

Please note that many API calls use JSON-encoded parameters and the Developer Test the parameters to be JSON-encoded. Please check the

JSON requests and results section under Documentation Nomenclature below and

Document Nomenclature

Ads API Documentation (Beta) | 2

At Facebook, we’re constantly working to match advertisers with users who are interested in We know that you see a better response from your customers

when you tailor ad creative and targeting criteria to specific sets of users, so we’ve created the your large and

to build applications that interact can build an application that uses the Facebook

onitor, and update your advertising campaigns, enabling you our campaigns based on their performance without relying on manual updates.

API is part of the Facebook Developer Platform. For general information about the

functionality that has been added to the which you can use to programmatically create, edit, manage, and get

in order to use the

This must be a real

, agree to the Terms of Service, then click “Save Changes.” , through which

will activate the key for use with the Ads API. The key looks f43418a3fc929e2bfa3d8dcc549351d2. We do not need your

access this application in the “Developers” list.

) allows you to test all the listed in this document when called with an application / account ID that has access to

encoded parameters and the Developer Test encoded. Please check the example

JSON requests and results section under Documentation Nomenclature below and individual

All bolded variables under a method are required Example: ads.getCampaigns list<ads_campaign> ads.getCampaigns(campaign_ids, bool include_deleted)

For the ads.get Campaigns method above, campaign_ids and include_deleted In addition, you will see parameters defined as: keyed on the parent name. For exampleelements of the targeting array in PHP $ad['targeting'] = array ("country" => "US", "keywords" => array("chocolate")); Furthermore, if the API call requires the parameter in JSON format, then entire array into a JSON string and pass the

JSON targeting string {"countries":["US"],"genders":[1],"relationship_statuses":[2,cities":[{"name":"atlanta, ga"}],"radius":"12","keywords":["movies"]}

Plain English translation: 18-43 year old males within a 12 mile radius of Atlanta, GA, USA that are either in a relationship or married and have the keyword “movies”

JSON adspec string Add ad info to the targeting JSON {"campaign_id":"6002276788163","name":"testing","bid_type":"1"ntries":["US"],"genders":[1],"relationship_statuses":[2,4],"age_min":"18","age_max":"43","cities":[{"name":"atlanta, ga"}],”radius”:”12”,"link_url":"http://www.YourUrl.com/"}}

This string will create one adgroup within campaign ID bid of $0.30 and the ad name “testing,” but that is not the title of the ad. This ad will target Males in a 12 mile radius of Atlanta, GA who are inkeyword “movies” in their profile. Please note the addition of the creative JSON string which specifies the ad title, body and the link.

JSON ads.estimateTargetingStats responseIf you pass the targeting string abovlook something like this:

18380pm_min":27,"cpm_median":29,"cpm_max":32}


variables under a method are required to be passed with some non-

list<ads_campaign> ads.getCampaigns(int64 account_id, list<int64> campaign_ids, bool include_deleted)

For the ads.get Campaigns method above, account_id has to be passed with some valueinclude_deleted can be passed as null.

ill see parameters defined as: parent.child. This translates into . For example, targeting.country and targeting.keywords

in PHP:

$ad['targeting'] = array ("country" => "US", "keywords" => array("chocolate"));

Furthermore, if the API call requires the parameter in JSON format, then you should tring and pass the string as the parameter.

{"countries":["US"],"genders":[1],"relationship_statuses":[2,3,4],"age_min":"18","age_max":"43","cities":[{"name":"atlanta, ga"}],"radius":"12","keywords":["movies"]}

43 year old males within a 12 mile radius of Atlanta, GA, USA that are either in a relationship or married and have the keyword “movies”.

Add ad info to the targeting JSON {"campaign_id":"6002276788163","name":"testing","bid_type":"1","max_bid":30,"targeting":{"countries":["US"],"genders":[1],"relationship_statuses":[2,4],"age_min":"18","age_max":"43","cities":[

”radius”:”12”,"keywords":["movies"]},"creative":{"title":"atl","body":"ftl",urUrl.com/"}}

This string will create one adgroup within campaign ID 6002276788163. It is a CPC ad with a bid of $0.30 and the ad name “testing,” but that is not the title of the ad. This ad will target Males in a 12 mile radius of Atlanta, GA who are in a relationship or married and have the keyword “movies” in their profile. Please note the addition of the creative JSON string which specifies the ad title, body and the link.

JSON ads.estimateTargetingStats response ng above into the ads.estimateTargetingStats method, the return will

":[{"location":3,"cpc_min":60,"cpc_median":62,"cpc_max":71,"cpm_min":27,"cpm_median":29,"cpm_max":32}


null value.

, list<int64>

has to be passed with some value but

translates into a nested array targeting.country and targeting.keywords are

you should encode the

4],"age_min":"18","age_max":"43","

43 year old males within a 12 mile radius of Atlanta, GA, USA that are either in a relationship

,"max_bid":30,"targeting":{"countries":["US"],"genders":[1],"relationship_statuses":[2,4],"age_min":"18","age_max":"43","cities":[

"keywords":["movies"]},"creative":{"title":"atl","body":"ftl",

. It is a CPC ad with a bid of $0.30 and the ad name “testing,” but that is not the title of the ad. This ad will target

a relationship or married and have the keyword “movies” in their profile. Please note the addition of the creative JSON string which

e into the ads.estimateTargetingStats method, the return will

":[{"location":3,"cpc_min":60,"cpc_median":62,"cpc_max":71,"c

To upload images, add the additional “image_file” parameter to the ‘image_file’ : ‘somefilename.jpg’). Tmultipart/form-data request and append the following to the raw API request Content-Disposition: form-data; filename="Content-Type: image/jpg [Raw file data here] Third-party sample code libraries for Facebook Platform have methods that you can extend for this purpose -- take a look at how the library you are using can see the available client libraries http://wiki.developers.facebook.com/index.php/Client_Libraries If you’re using PHP with our facebookapi_restlib file included, name to your ad’s creative JSON array. put your creative into your ad_group spec $adgroup_spec['creative']['image_file'] = $image_file_name;ads_createAdGroups($account_id, $adgroup_spec, imagedata)

Data Types int 32-bit integer int64 64-bit integer bool boolean string string json_string JSON-encoded object list<x> array of values of type x

Ads Structs ads_account struct ads_account { int64 account_id, string name, int daily_spend_limit, list<ads_account_user> users,


add the additional “image_file” parameter to the creative JSON ). Then change your createAdGroups API request to a

and append the following to the raw API request:

data; filename="yourimagefile.jpg"

party sample code libraries for Facebook Platform have methods that you can extend for look at how the library you are using makes the photos.upload call. client libraries for Facebook Platform at

http://wiki.developers.facebook.com/index.php/Client_Libraries

HP with our facebookapi_restlib file included, you can just add the image file name to your ad’s creative JSON array. The example snippet below assumes you’ve already put your creative into your ad_group spec. Adding the image file is the last step:

group_spec['creative']['image_file'] = $image_file_name; ads_createAdGroups($account_id, $adgroup_spec, imagedata)

int64 account_id, string name, int daily_spend_limit, list<ads_account_user> users,


JSON (for example, API request to a

party sample code libraries for Facebook Platform have methods that you can extend for hotos.upload call. You

just add the image file assumes you’ve already

the image file is the last step:

string currency} Notes: • Calls to ads.getAccounts• name is the name of the account. The name can have at most • daily_spend_limit is defined in US cents• currency is a 3 character ISO code for currency of account (e.g. USD)

currencies currently include: Australian Dollars (AUD) Chilean Peso (CLP) Danish Krone (DKK) Norwegian Krone (NOK) Turkish Lira (TRY) ads_account_user struct ads_account_user { int64 uid, }

Notes: • uid is the Facebook user id

ads_campaign struct ads_campaign { int64 account_id, int64 campaign_id, string name, int time_start, int time_stop, int daily_budget, ads_run_status campaign_status, int lifetime_budget} Notes: • account_id is the Ads account ID• campaign_id is the ID of the campaign you are editing or getting stats for, not used in

create_campaigns • name is at most 30 characters • time_start and time_stop• time_stop can’t be more than one year in the future• daily_budget defined in cents USD• lifetime_budget defined in cents USD • lifetime_budget and daily_budget ads_update_campaigns_resultstruct ads_update_campaigns_result { list<int64> updated_campaigns; map<int64, list<string>> failed_campaigns;


string currency

ads.getAccounts return an array with these elements is the name of the account. The name can have at most 30 characters

is defined in US cents, with 100 cents USD as the minimum valueis a 3 character ISO code for currency of account (e.g. USD). Supported

British Pound (GBP) Canadian Dollars (CAD)Colombian Peso (COP) Euro (EUR) Hong Kong Dollar (HKD) Japanese Yen (JPY)Swedish Krona (SEK) Swiss Fanc (CHF)US Dollars (USD) Venezuelan Bolivar (VEF)

struct ads_account_user {

user id for the application user

int64 account_id, int64 campaign_id,

int time_start, int time_stop,

y_budget, ads_run_status campaign_status,

lifetime_budget

is the Ads account ID is the ID of the campaign you are editing or getting stats for, not used in

is at most 30 characters time_stop are unix timestamps

can’t be more than one year in the future defined in cents USD. 100 cents USD is the minimum value

defined in cents USD daily_budget cannot be zero

s_result struct ads_update_campaigns_result { list<int64> updated_campaigns; map<int64, list<string>> failed_campaigns;


30 characters minimum value

. Supported

Canadian Dollars (CAD)

Japanese Yen (JPY) Swiss Fanc (CHF) Venezuelan Bolivar (VEF)

is the ID of the campaign you are editing or getting stats for, not used in

is the minimum value

}

Notes: • When ads.createCampaigns

ads_update_campaigns_result.updated_campaigns

campaigns that were created. could not be created. The index is the same as the index specified in when ads.createCampparticular campaign.

• When ads.updateCampaigns

ads_update_campaigns_result.updated_campaigns

campaigns that were updated. could not be updated and the reasons why.

ads_adgroup struct ads_ad { int64 ad int64 campaign_id, string name, ads_run_status ad ads_ad_bid_type bid_type, int max_bid, ads_targeting targeting, ads_creative creative, } Notes: • name is at most 30 characters • max_bid defined in cents • targeting and creative

creative elements of the AdGroup you are creating or querying• Paused ads can return either

CAMPAIGN_PAUSED, unpausing the campaign will also unpausegroup returns ADGROUP_PAUSED

ads_update_adgroups_result struct ads_update_adgroups list<int64> update_ad map<int64, list<string>> } Notes:

• When ads.createAdGroups ads_update_adgroups_result.updated_adgroups

groups that were created. The groups that could not be created. The index is the same as the index specified in adgroup_specs when ads.createAdGroups messages for that particular ad group.

• When ads.updateAdGroups

ads_update_adgroups_result.updated_adgroups


ads.createCampaigns is called, ads_update_campaigns_result.updated_campaigns contains the IDcampaigns that were created. failed_campaigns contains the list of campaigns that could not be created. The index is the same as the index specified in campaign_specs

ads.createCampaigns is called. The value is a list of error messages for that

ads.updateCampaigns is called, ads_update_campaigns_result.updated_campaigns contains the IDcampaigns that were updated. failed_campaigns contains the list of campaigns that could not be updated and the reasons why.

int64 adgroup_id, int64 campaign_id, string name, ads_run_status adgroup_status, ads_ad_bid_type bid_type, int max_bid, ads_targeting targeting, ads_creative creative,

is at most 30 characters

are JSON-encoded strings representing the targeting and creative elements of the AdGroup you are creating or querying Paused ads can return either ADGROUP_PAUSED or CAMPAIGN_PAUSED. In the case of

, unpausing the campaign will also unpause the ad group. If the adADGROUP_PAUSED, however, you will have to unpause that specific ad

_result groups_result { adgroups,

map<int64, list<string>> failed_adgroups,

ads.createAdGroups is called, ads_update_adgroups_result.updated_adgroups contains the IDgroups that were created. The failed_adgroups element contains the list of ad groups that could not be created. The index is the same as the index specified in

ads.createAdGroups is called. The value is a list of error messages for that particular ad group.

ads.updateAdGroups is called, ads_update_adgroups_result.updated_adgroups contains the ID


contains the IDs of the contains the list of campaigns that

campaign_specs is called. The value is a list of error messages for that

contains the IDs of the of campaigns that

encoded strings representing the targeting and

. In the case of group. If the ad

, however, you will have to unpause that specific ad group.

contains the IDs of the ad element contains the list of ad

groups that could not be created. The index is the same as the index specified in is called. The value is a list of error

contains the IDs of the ad

groups that were updated. not be updated and the reasons why.

ads_creative struct ads_creative { int64 creative_id, int64 account_id, string title, string body, string link_url, } Notes: • ads_creative is subject to several constraints, including:

o title must be at least 1 character and at most 25 characters o body must be at least 1 character and at most 135 characterso creative_id is only used if you want to reuse a creative from a different ad

ads_targeting struct ads_targeting { list<string> countries list<ads_id_name_map> cities, list<ads_id_name_map> regions, list<ads_targeting_gender> genders, list<ads_id_name_map> college_networks, list<ads_id_name_map> int age_min, int age_max, list<ads_targeting_education> education_statuses, list<int> college_years, list<string> list<ads_targeting_political> political_views, list<ads_targeting_relationship> relationship_statuses, list<string> keywords, list<ads_targeting_gender> interested_in, int radius,} Notes: • for countries, regions, cities

can use the ads.getAutoCompleteData Methods” to get targetable options

• min_age must be 13 years or higher• college_years is defined

[2008, 2009] • keywords are matched to user profile data to better target ads• attribute lists can contain at most 50 elements • for cities in the US or Canada

outside the US and Canada, NY” or “Paris, France”.


groups that were updated. failed_adgroups contains the list of ad groups that could not be updated and the reasons why.

int64 creative_id, int64 account_id, string title, string body, string link_url,

is subject to several constraints, including: must be at least 1 character and at most 25 characters

must be at least 1 character and at most 135 characters is only used if you want to reuse a creative from a different ad

> countries,

list<ads_id_name_map> cities, list<ads_id_name_map> regions, list<ads_targeting_gender> genders, list<ads_id_name_map> college_networks, list<ads_id_name_map> work_networks, int age_min, int age_max, list<ads_targeting_education> education_statuses, list<int> college_years,

college_majors, list<ads_targeting_political> political_views, list<ads_targeting_relationship> relationship_statuses, list<string> keywords, list<ads_targeting_gender> interested_in, int radius,

countries, regions, cities, college_networks, work_networks

ads.getAutoCompleteData method documented under “AdGroup Service able options.

be 13 years or higher defined as the graduating year of a user and is in calendar years, e.g.,

are matched to user profile data to better target ads attribute lists can contain at most 50 elements

in the US or Canada, include the two letter state or province codeoutside the US and Canada, include the whole country name. For example, use


contains the list of ad groups that could

is only used if you want to reuse a creative from a different ad

list<ads_targeting_relationship> relationship_statuses,

, college_networks, work_networks, you AdGroup Service

in calendar years, e.g.,

include the two letter state or province code. For cities , use “New York,

time_ranges This is a JSON string of time_ranges used in the reporting functionssending time ranges, one using UNIX Each stats call allows you to pull stats for multiple campaigns or time_ranges are expected to be an array of these strings. '{"time_range":{"day_start":{"month":9,"day":11,"year":2009},"day_stop":{"month":9,"day":13,"year":2009}}}' '{"time_start":1252537200,"time_s

To get lifetime stats use: '{"time_start":0,"time_stop":0

To get stats ending as recently as possible use: '{"time_start":1252537200,"time_stop":0

ads_stats struct ads_stats { int64 id, int time_start, int time_stop, int impressions, int clicks, int spent, } Notes: • this is the structure returned when you call • id contains the ID of some system entity, e.g., campaign or ad • spent defined in cents USD• clicks and impressions

AdGroup or campaign ID • time_start and time_stop

Ads Enums Ads Enums Ads Enums Ads Enums campaign_status enum campaign_status { ACTIVE = 1, PAUSED = 2, DELETED = 3,

ads_run_status enum ads_run_status { ACTIVE = 1, PAUSED = 2,


JSON string of time_ranges used in the reporting functions. There are two options for UNIX time stamps and other using MM-DD-YYYY notation.

Each stats call allows you to pull stats for multiple campaigns or ad groups at once, so the time_ranges are expected to be an array of these strings. Examples of each option are below:

'{"time_range":{"day_start":{"month":9,"day":11,"year":2009},"day_stop":{"month":9,"day":13,"year":2009}}}'

2537200,"time_stop":1252623600}'

{"time_start":0,"time_stop":0}'

To get stats ending as recently as possible use:

{"time_start":1252537200,"time_stop":0}'

int time_start,

int impressions,

this is the structure returned when you call getCampaignStats or getAdGroupStatsof some system entity, e.g., campaign or ad

defined in cents USD are the aggregate number of clicks and impressions for the

time_stop will always be returned in UNIX time


. There are two options for YYYY notation. at once, so the

Examples of each option are below:

'{"time_range":{"day_start":{"month":9,"day":11,"year":2009},"day_stop

getAdGroupStats

are the aggregate number of clicks and impressions for the

DELETED = 3, PENDING_REVIEW = 4, DISAPPROVED = 5, CAMPAIGN_PAUSED = 8, ADGROUP_PAUSED = 9, }

Notes: • PAUSED is deprecated. Use

groups within that campaign. • When you unpause a campaign, however, the

CAMPAIGN_PAUSED will also become unpaused.• ADGROUP_PAUSED indicates the adgroup is paused independently of the campaign’s

status. Use ADGROUP_PAUSED ads_ad_bid_type enum ads_ad_bid_type { CPC = 1, CPM = 2, } ads_targeting_gender enum ads_targeting_gender { MALE = 1, FEMALE = 2, } ads_targeting_relationship enum ads_targeting_relationship { SINGLE = 1, IN_RELATIONSHIP = 2, MARRIED = 3, ENGAGED = 4, }

ads_targeting_political enum ads_targeting_political { LIBERAL = 1, MODERATE = 2, CONSERVATIVE = 3, } ads_targeting_education enum ads_targeting_education { HIGH_SCHOOL = 1, UNDERGRAD = 2, ALUM = 3, }


is deprecated. Use CAMPAIGN_PAUSED to pause campaigns and the roups within that campaign.

When you unpause a campaign, however, the ad groups whose status was previouslywill also become unpaused.

indicates the adgroup is paused independently of the campaign’s ADGROUP_PAUSED to pause individual ad groups.

enum ads_targeting_gender {

ads_targeting_relationship enum ads_targeting_relationship { SINGLE = 1, IN_RELATIONSHIP = 2, MARRIED = 3, ENGAGED = 4,

enum ads_targeting_political { LIBERAL = 1, MODERATE = 2, CONSERVATIVE = 3,

enum ads_targeting_education {


to pause campaigns and the ad

roups whose status was previously

indicates the adgroup is paused independently of the campaign’s

Account Service MethodsAccount Service MethodsAccount Service MethodsAccount Service Methods ads.getAccounts list<ads_account> ads.getAccounts()

Returns an array of all accounts associated with the currently logged in user.

Campaign Service Methods Campaign Service Methods Campaign Service Methods Campaign Service Methods ads.getCampaigns list<ads_campaign> ads.getCampaigns(campaign_ids, bool include_deleted)

Gets all campaigns from the account. If campaigns are returned. If campaign_idsreturned.

ads.createCampaigns ads_campaign_result ads.createCampaigncampaign_specs) Creates a campaign. The parameter ads_campaign structs with the following required attributes defined: account_id name daily_budget The following optional attributes can be defined: time_start time_stop All other attributes are ignored. ads.updateCampaigns ads_campaign_result ads.updateCampaigncampaign_specs) Updates a campaign. The parameter ads_campaign structs with the following required attributes defined: campaign_id The following optional attributes name


Account Service MethodsAccount Service MethodsAccount Service MethodsAccount Service Methods

list<ads_account> ads.getAccounts()

all accounts associated with the currently logged in user.

Campaign Service Methods Campaign Service Methods Campaign Service Methods Campaign Service Methods

ads.getCampaigns(int64 account_id, list<int64> campaign_ids, bool include_deleted)

Gets all campaigns from the account. If include_deleted is false, only non-deleted campaign_ids is specified, only campaigns with specified ID

ads_campaign_result ads.createCampaigns(int64 account_id, list

Creates a campaign. The parameter campaign_specs is an array of JSON-encoded with the following required attributes defined:

attributes can be defined:

ads.updateCampaigns(int64 account_id, lis

Updates a campaign. The parameter campaign_specs is an array of JSON-encoded with the following required attributes defined:

The following optional attributes are the only ones that can be updated:


, list<int64>

deleted pecified IDs are

list

encoded

list

encoded

daily_budget time_start time_stop campaign_status The campaign_status enum is defined in the “Ads Enums” section above. attributes that you wish to update. passed will remain unchanged.

ads.getCampaignStats list<ads_stats> ads.getCampaignStats(campaign_ids, bool include_deleted, Gets basic stats for the campaigns in the account over different time ranges. If include_deleted is false, only nonspecified, only campaigns with specified ids are returned. array defined in the “Ad Structs”

AdGroup Service MethodsAdGroup Service MethodsAdGroup Service MethodsAdGroup Service Methods ads.getAutoCompleteDatalist<> ads.getAutoCompleteData

This API call returns all possible countries, regions and citieslike the example below: array ( 'colleges' => array ( 0 => array ( 'value' => 'Harvard', …

ads.getAdGroups list<ads_adgroup> ads.getAdGroups(campaign_ids, list<int64> adgroup_ids, bool include_deleted)

Gets a set of ad groups in the account. include_deleted filter the list of ad groups to be returned.

ads.createAdGroups ads_update_adgroups_result ads.createAdGroups(adgroup_specs)


is defined in the “Ads Enums” section above. Only pass the attributes that you wish to update. All other attributes are ignored and attributes that aren’t

list<ads_stats> ads.getCampaignStats(int64 account_id, list<int64> , bool include_deleted, json_string time_ranges

Gets basic stats for the campaigns in the account over different time ranges. If is false, only non-deleted campaigns are returned. If campaign_ids

specified, only campaigns with specified ids are returned. time_ranges is a JSON section.

AdGroup Service MethodsAdGroup Service MethodsAdGroup Service MethodsAdGroup Service Methods

getAutoCompleteData utoCompleteData(int64 account_id)

This API call returns all possible colleges, college_majors, workplaces, locales, cities. Each category is an array nested within the return array

list<ads_adgroup> ads.getAdGroups(int64 account_id, list<int64> campaign_ids, list<int64> adgroup_ids, bool include_deleted)

a set of ad groups in the account. campaign_ids, adgroup_ids, and filter the list of ad groups to be returned.

ads_update_adgroups_result ads.createAdGroups(int64 account_id,


Only pass the and attributes that aren’t

int64 account_id, list<int64> json_string time_ranges)

campaign_ids is is a JSON-encoded

colleges, college_majors, workplaces, locales,

is an array nested within the return array

, list<int64> campaign_ids, list<int64> adgroup_ids, bool include_deleted)

int64 account_id, list

Creates ad groups. The parameter ads_adgroup structs with the following required attributes defined: • campaign_id

• name

• bid_type

• max_bid

• targeting

o At minimum, you must specify country targetingcodes)

And EITHER:

• creative.title

• creative.body

• creative.link_url

• creative.link_type

OR:

• creative.creative_id (provide existing creative_id to recycle a

creative)

The following optional attributes can also be defined:

• targeting.cities

• targeting.regions

• targeting.genders

• targeting.college_networks

• targeting.work_networks

• targeting.age_min

• targeting.age_max

• targeting.education_statuses

• targeting.college_years

• targeting.college_majors

• targeting.political_views

• targeting.relationship_statuses

• targeting.keywords

• creative.image *** see notes

All other attributes are ignored. For image uploads, you’ll need to use You can also take a look at the sample app


Creates ad groups. The parameter ad_specs is an array of JSON-encoded array of with the following required attributes defined:

you must specify country targeting (a list of two letter ISO country

creative.creative_id (provide existing creative_id to recycle a

attributes can also be defined:

targeting.college_networks

targeting.work_networks

targeting.education_statuses

targeting.college_years

targeting.college_majors

targeting.political_views

targeting.relationship_statuses

*** see notes on image upload

need to use a multi-part MIME type, as in the “Images” section abovesample app for more detail.


encoded array of

list of two letter ISO country

creative.creative_id (provide existing creative_id to recycle a

, as in the “Images” section above.

ads.updateAdGroups ads_ad_result ads.updateAdGroups(

Updates an adgroup. The parameter adgroup_specs is astructs with the following required attributes defined: • adgroup_id The following optional attributes can be defined:

• name

• max_bid

• ad_status

The API will update whatever parameters you specify in each you only want to change the name of string for that ad group. Example:

ads.getAdGroupStats list<ads_stats> ads.getAdGroupStats(campaign_ids, list<int64> adgroup_idslist<ads_time_range> time_ranges

Gets stats for a list of ad groups in the account. include_deleted are used to filter the list of ad groups. defined in the “Ads Structs” section above.

ads.getAdGroupTargetingmap<int64, ads_targeting> ads.getAdTargeting(list<int64> campaign_ids, include_deleted)

Gets targeting (a map of adgroup campaign_ids, adgroup_ids

groups. ads.getAdGroupCreativesmap<int64, ads_creatives> ads.list<int64> campaign_ids, include_deleted)

Gets creatives (a map of adgroup campaign_ids, adgroup_ids

groups.


ads_ad_result ads.updateAdGroups(int64 account_id, list adgroup_specs

Updates an adgroup. The parameter adgroup_specs is an array of JSON encoded ads_adgroup with the following required attributes defined:

The following optional attributes can be defined:

The API will update whatever parameters you specify in each adgroup struct. For exampleyou only want to change the name of AdGroup 123456, pass only the name within the JSON

roup. Example: [{‘”adgroup_id” : 123456, “name” : “new name”}]

list<ads_stats> ads.getAdGroupStats(int64 account_id, list<int64> list<int64> adgroup_ids, bool include_deleted,

list<ads_time_range> time_ranges)

Gets stats for a list of ad groups in the account. campaign_ids, adgroup_idsare used to filter the list of ad groups. The time_ranges structure is

section above.

Targeting map<int64, ads_targeting> ads.getAdTargeting(int64 account_idlist<int64> campaign_ids, list<int64> adgroup_ids, bool

group IDs to ads_targeting) for a list of ad groups in the account. campaign_ids, adgroup_ids, and include_deleted are used to filter the list of ad

Creatives 64, ads_creatives> ads.getAdCreatives(int64 account_id

list<int64> campaign_ids, list<int64> adgroup_ids, bool

group IDs to ads_creative) for a list of ad groups in the account. campaign_ids, adgroup_ids, and include_deleted are used to filter the list of ad


adgroup_specs)

JSON encoded ads_adgroup

roup struct. For example, if the name within the JSON

ame” : “new name”}]

, list<int64> , bool include_deleted,

campaign_ids, adgroup_ids, and structure is

int64 account_id,

) for a list of ad groups in the account. are used to filter the list of ad

int64 account_id,

) for a list of ad groups in the account. are used to filter the list of ad

ads.estimateTargetingStatsads_targeting_stats ads.estimateTargetingStats(ads_targeting targeting_spec

Returns statistics based on the targeting criteria specified. CPC/CPM values are based on the currency specified.


ads.estimateTargetingStats ads_targeting_stats ads.estimateTargetingStats(int64 account_idads_targeting targeting_spec, string currency)

Returns statistics based on the targeting criteria specified. CPC/CPM values are based on the


int64 account_id,

Returns statistics based on the targeting criteria specified. CPC/CPM values are based on the

Face Book Ads API

Documents