Graph API Version

Store Visits Objective

Access to the Ads and Insight API for Store Visits is provided on a whitelist basis only. Please contact your partner manager.

The Store Visits objective aims to bridge the gap between the online and offline worlds to help marketers achieve their objective of driving customers into brick and mortar stores.

Placements

Currently available for Facebook (Desktop/Mobile)

Delivery optimization

There are two optimization options available for the new Store Visits objective:

  • Reach Optimization is available to all advertisers. It optimizes for daily unique reach and shows “Impressions” as the default metric within Ads Manager reporting.

  • Store Visits Optimization is available to eligible advertisers. It optimizes for the lowest cost per attributed store visit by increasing delivery towards customers who are most likely to visit a store. Store visits is the default metric within Ads Manager reporting when available.

Create Ads

To create dynamic ads for the Store Visits objective, your page must use locations.

Note

  • The campaign must have its objective set to STORE_VISITS.
  • The campaign must have its promoted_object set to the corresponding <PARENT_PAGE_ID>.
  • The ad set's promoted_object and targeting attribute must contain a place_page_set_id of a <PAGE_SET_ID>
  • The ad set's optimization_goal must be set to STORE_VISITS or REACH
  • The ad set's billing_event should be set to IMPRESSIONS

To create dynamic ads using Store Vists, follow these steps:

  1. Create a PageSet
  2. Create a Campaign
  3. Create an Ad Set
  4. Create an Ad Creative
  5. Create an Ad

Step 1. Creating a PageSet

The PageSet will ultimately be used in targetting and as the promoted object.

Creating a PageSet involves three-sub steps:

  • Gathering Child Locations
  • Building a "Locations JSON" structure to create the PageSet.
  • Create the PageSet with the Locations JSON

Step 1a. Gathering all Child Locations from Parent

The first step to creating a PageSet is to output all the locations from a Page. <PARENT_PAGE_ID> is the ID of the Parent page of your Parent-child structure. the following call will retreive all the child pages of the parent page and return the longitude and latitude for each location.

curl -G \
  -d "fields=location{latitude,longitude},is_permanently_closed" \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "limit=30000" \
  https://graph.facebook.com/v2.8/<PARENT_PAGE_ID>/locations

Sample output:

{
    "data": [
        {
            "location": {
                "latitude": 29.173384,
                "longitude": 48.098807
            },
            "is_permanently_closed": false,
            "id": "1788030244802584"
        },
        {
            "location": {
                "latitude": 29.303635,
                "longitude": 47.937725
            },
            "is_permanently_closed": false,
            "id": "261533444245300"
        },
        {
            "location": {
                "latitude": 29.302303,
                "longitude": 47.933178
            },
            "is_permanently_closed": false,
            "id": "179435399132774"
        },
        {
            "location": {
                "latitude": 29.302591,
                "longitude": 47.931801
            },
            "is_permanently_closed": false,
            "id": "1790317704582144"
        }
    ],
    "paging": {
        "cursors": {
            "before": "MTc4ODAzMDI0NDgwMjU4NAZDZD",
            "after": "MTA4MTU4NjU5NjA5MDA4"
        }
    }
}

Step 1b. Creating a Locations JSON Structure

Iterate through each entry in the previous return, ensure the locations are open for business (e.g. is_permanently_closed field) and get the estimated radius (two GET Graph API calls). Alternatively, consider using a Batched API call to generate the values (an example is provided below).

Individual Requests

The following call is made against using each Child Page's Latitude and Longitude (from the previous JSON in Step 1a) to return the estimated radius for each location.

curl -X GET \
"https://graph.facebook.com/v2.8/search?type=adradiussuggestion&latitude=<CHILD_PAGE_LATITUDE>&longitude=<CHILD_PAGE_LONGITUDE>&access_token=<ACCESS_TOKEN>"

Batching Requests

To send multiple requests at once you can also batch multiple requests into a single request as in the following example:

curl \
  -F "access_token=<ACCESS_TOKEN>" \
  -F "include_headers=false" \
  -F "batch=[
    {
      \"method\": \"GET\",
      \"relative_url\": \"/v2.8/search?type=adradiussuggestion&latitude=29.173384&longitude=48.098807\"
    },
    {
      \"method\": \"GET\",
      \"relative_url\": \"/v2.8/search?type=adradiussuggestion&latitude=29.303635&longitude=47.937725\"
    }
  ]" \
  "https://graph.facebook.com"

Final Locations JSON Structure

Using the radius and distance_unit from the previous call(s) and the <CHILD_LOCATION_ID> as the page_id to create the following JSON structure - this is the final Locations JSON Structure:

Example Locations JSON Structure:

[
    {
      "page_id": 1788030244802584,
      "radius": 1,
      "distance_unit": "mile"
    },
    {
      "page_id": 261533444245300,
      "radius": 1,
      "distance_unit": "mile"
    }
]

Step 1c: Creating the Pageset with the Locations JSON

The maximum number of places within a Page Set is 10000

Make the following call to make the PageSet.

It will return an id of the PageSet which needs to be used in the subsequent steps.

  curl -X POST \
   -d "name=My Grand Pageset" \
   -d "parent_page=<PARENT_PAGE_ID>" \
   -d "pages=<LOCATIONS_JSON_STRUCTURE>" \
   -d "access_token=<ACCESS_TOKEN>" \
   "https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/ad_place_page_sets/"

The above call will return the <PAGE_SET_ID> as the following:

{
  "id": <PAGE_SET_ID>
}

If the number of pages becomes too large for a cURL call you can create a text file of the LOCATIONS_JSON_STRUCTURE and pass it in to the pages attribute using a flag: -F "pages=<locations_json_structure.txt"

Step 2: Create A Campaign

Create a campaign with objective set to STORE_VISITS and your parent page ID as promoted object.

curl -X POST \
 -d "name=Store Visits Campaign" \
 -d "objective=STORE_VISITS" \
 -d "promoted_object={'page_id':'<PARENT_PAGE_ID>'}" \
 -d "status=PAUSED" \
 -d "access_token=<ACCESS_TOKEN>" \
 "https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/campaigns"

Reference: Campaign

Step 3: Create An Ad Set

Create an ad set to contain your ad.

curl \
  -F 'name=Store Visits Ad Set' \
  -F 'promoted_object={"place_page_set_id":"<PAGE_SET_ID>"}' \
  -F 'optimization_goal=STORE_VISITS' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'is_autobid=true' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F "targeting={
    'place_page_set_ids': ['<PAGE_SET_ID>'],
    'device_platforms': ['mobile','desktop'],
    'facebook_positions': ['feed']
  }" \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/adsets

Ads targeting locations more than 50 miles away from the nearest page location (local page) will be invalidated at delivery time.

Reference: Ad setReference: Targeting specsReference: Page locations

Step 4: Create An Ad Creative

Creative Template

Dynamic creation of Store Visits ads allow you to customize your creative using a set of template placeholders, these will be replaced at runtime with:

  • Data from the user nearest page location, if dynamic_ad_voice is set to DYNAMIC.
  • Data from your main page, if dynamic_ad_voice is set to STORY_OWNER.

Available placeholders:

  • {{page.location.city}}
  • {{page.location.region}}
  • {{page.location.street_address}}
  • {{page.name}}
  • {{page.phone_number}}

Call To Actions

Store Visits call-to-action buttons (CTAs) can be dynamized too:

  • When using GET_DIRECTIONS or CALL_NOW, the CTA value field is not required. Users will automatically be directed to nearest location or prompted to call the nearest location phone number.
  • MESSAGE_PAGE is allowed only if dynamic_ad_voice is set to STORY_OWNER. Messages will be delivered to the main page.
  • This is an optional field. For Single Ads, if not specified, we will display Like Page button.
dynamic_ad_voicetype in call_to_action

DYNAMIC

CALL_NOW
GET_DIRECTIONS

STORY_OWNER

CALL_NOW
GET_DIRECTIONS
LEARN_MORE
MESSAGE_PAGE

Examples

Create an ad creative using dynamic page name and city:

curl \
  -F 'dynamic_ad_voice=DYNAMIC' \
  -F 'object_story_spec={ 
    "page_id": "<PARENT_PAGE_ID>", 
    "template_data": { 
      "description": "Ad Description", 
      "link": "<URL>", 
      "message": "Ad Message for {{page.location.city}}", 
      "name": "{{page.name}}", 
      "picture": "<IMAGE_URL>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/adcreatives
Reference: Ad creative


Ad Creative with Map Card

To use a Map Card add the following place_data attribute structure within a child attachment in the child_attachments field in your Ad Creative.

In the following example, the Map card (with Store Locator Facebook Link Destination) is the second item in the child_attachments array. It is a requirement to have at least one item in addition to the Map card:


curl \ -F 'dynamic_ad_voice=DYNAMIC' \ -F 'object_story_spec={ "page_id": "<PARENT_PAGE_ID>", "template_data": { "description": "Ad Description", "link": "<URL>", "message": "Ad Message for {{page.location.city}}", "name": "{{page.name}}", "child_attachments":[ { "description": "Come visit us!", "link": "http://yourweburl.com", "name": "{{page.location.street_address}} - {{page.location.city}}", "call_to_action": { "type":"GET_DIRECTIONS" }, }, { "link": "https://fb.com/store_locator", "name": "Check out our stores.", "place_data": { "type":"DYNAMIC" }, } ] } }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/adcreatives

Store Locator (Link Destination)

When creating an Ad, if you set the link to 'https://fb.com/store_locator' the ad will render with the Store Locator as the link destination.

Step 5: Create An Ad

Create an ad as usual:

curl \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/ads

To be able to create Store Visits ads your Page/Ad Account must be approved for Store Visit Measurement. Otherwise, an error similar to 'Reach estimate isn't available because 'store_visit' isn't a valid action type.' will throw

Reference: Ad

Enabling the Store Visits metric in Ads Manager, accessing the API and insights documentation requires a client to be whitelisted

Store Visits Measurement

Store visits is an estimated metric based on data from users with location services enabled. It ultimately offers store visit measurement and optimization for the Store Visits objective.

Store visits are based upon clicks and on attention (impressions). Attention (impressions) are the number of times people paid more attention to your ads than they usually do to other posts on Facebook.

Store visit measurement is only available for multi-location Store Visits and Local Awareness campaigns.

The following sections describe the new features added to the:

Generally, the changes relate to reporting for the following items:

  • Store Visits: The number of estimated visits to your business locations as a result of your ads
  • Cost per Store Visit: The average cost for each estimated visit to your business locations as a result of your ads

Ads Manager Interface

Within Ads Manager new columns (categorized under "ENGAGEMENT: ACTIONS") will be available in the reporting interface for Store Visits and the Cost per Store Visit.

The default reporting view includes a conversion funnel showing total impressions, attention (impressions), and store visits along with conversion rates. It is also possible to show a time-series chart of store visits based on day of impression.

Store visit data will only be available for business locations that the Facebook team have confirmed are measurable for a campaign.

Insights API

Reference Docs

Insights can be drawn from the Insights API where two additional fields are returned within the general insights call: cost_per_store_visit and store_visits

The fields cost_per_store_visit and store_visits are available by whitelist only. Please contact your partner manager.

A sample call would resemble:

curl -G \
-d "fields=cost_per_store_visit,store_visits" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v2.8/<AD_OBJECT_ID>/insights"

A sample output would look like:

{
    "data": [
        {
            "cost_per_store_visit": "0.999999",
            "store_visits": {
                "point_estimate": 1000,
                "high_estimate": 1385,
                "low_estimate": 900
            },
            "date_start": "2016-09-04",
            "date_stop": "2016-10-02"
        }
    ],
    "paging": {
        "cursors": {
            "before": "MAZDZD",
            "after": "MAZDZD"
        }
    }
}

The call return the cost per store visit and the estimated value of the store visits:

FieldDescription

point_estimate

int32

The point prediction of the value