Ads Targeting Migration Guide to Bing Geo

For targeting locations, LinkedIn is migrating to a new geo data source (i.e. Bing geo). If you are a partner using LinkedIn standardized geo locations to create campaigns for ads targeting, please continue reading this guide. This doesn't impact UGC and Shares yet.

The new geo data enables customers to target millions of new geo locations, including counties and cities, providing a more comprehensive and accurate geo targeting experience. Currently, there are ~6k standardized locations, primarily in US. With Bing geo, around 2.6 million locations will be available at launch, and a large number of international locations. This migration guide provides the details of migrating from current geo endpoints/values to the new ones.

Note

All use of the Microsoft Bing Maps location data is subject to Microsoft Bing Maps and MapPoint Web Service End User Terms of Use and Embedded Maps Service Terms of Use and the Microsoft Privacy Statement which are now incorporated into our Marketing Developer Program Terms. By accessing any Microsoft Bing Maps location data, you are agreeing to be bound by these Microsoft terms.

How Migration is Planned

The migration effort is divided among the following phases:

  1. Phase 1: Migrate from legacy geo API to typeahead and urn-to-name resolver API to retrieve locations.
  2. Phase 2: Start using Bing geo locations in ad campaigns, in place of legacy locations.
  3. Phase 3: Only Bing geo locations will be accepted in ad campaigns. Legacy locations can no longer be used for campaign creation, campaigns with legacy locations will be rejected.

Migration Phase 1: Move to Typeahead and urn-to-name resolver API from legacy geo API

In this phase, we recommend partners to use the typeahead API to retrieve legacy geo locations along with urn-to-name resolver API instead of legacy geo API.

Steps involved with Phase 1

  1. Partners have 3 months starting from 8/1/2019 to 10/31/2019 to migrate from legacy geo API to new typeahead API.
  2. During phase 1, typeahead will return legacy geo locations, such as “urn:li:country:us”.
  3. Typeahead API will NOT return Bing locations in phase 1. Bing locations will be available starting in phase 2.
  4. In phase 2, the Bing geo locations will be returned as geo urn IDs via the Typeahead API. To convert geo urn IDs to localized labels, partners need to call the urn-to-name resolver API.
  5. Ad campaigns still accepts the legacy locations during phase 1.

API Mapping for migration

Geo type Get_all endpoint Get_all methods Migrate to
Country group /v2/countryGroups GET/GET_ALL/BATCH_GET targeting typeahead finder and urn-to-name resolver API
Country /v2/countries GET/BATCH_GET/GET_ALL/FINDER countryGroupN targeting typeahead finder and urn-to-name resolver API
States /v2/states GET/BATCH_GET/GET_ALL/FINDER country targeting typeahead finder and urn-to-name resolver API
Regions /v2/regions GET/BATCH_GET/GET_ALL/FINDER countries/FINDER states/FINDER standardizedLocation targeting typeahead finder and urn-to-name resolver API

Examples of using typeahead finder in place of legacy geo API

  • Retrieve legacy geo locations using get_all API example.
  • Retrieve legacy geo locations using typeahead API example.

Example of using urn-to-name resolver API

  • To get localized name for a legacy geo location example.

Note: In Find Entities by Typeahead, please do not use entityType:

GET https://api.linkedin.com/v2/adTargetingEntities?q=TYPEAHEAD&facet={adTargetingFacet URN}&query={Search Query}

Are there any special rule changes for Bing Geo locations?

  1. LinkedIn has removed the existing parent-child relationship validation rule on geo entities. Partners no longer have to implement and support complex geo rules. Ad campaign creation won’t return error response in this scenario.
  2. Example, if the United States and California (subregion or “children” of United States) are added to a campaign, our current campaign API fails the campaign creation and requires to remove one of them. After migration, this campaign creation will no longer error out.

After switching to targeting typeahead finder, it's not possible to get a complete list of all countries, regions etc. We require Partners to use typeahead for querying locations rather than handle a full list.

After phase 1, following APIs that returns legacy geo should not be used for ads Targeting.

  1. Get all continent
  2. Get all countries
  3. Get all states
  4. Get all regions
  5. Get all countries of a continent
  6. Get all states of a country
  7. Get all regions of a state

After switching to the typeahead finder endpoint and implementing urn-to-name resolver API for localized name for Ads location targeting, migration to phase 1 is complete.

Migration Phase 2: Use Bing Geo location in Ad campaigns

In Phase 2, LinkedIn starts serving Bing geo locations via the Typeahead API. We also auto migrate existing campaigns to the new geo data. Partners should start using the Bing geo locations via the typeahead API while creating campaigns. Phase 2 commences from 12/12/2019 and ends by 3/31/2020.

Steps involved in Phase 2

  1. Typeahead API will return ONLY Bing locations: Refer to this example.
  2. Ad campaigns will start accepting Bing locations. Although legacy locations are acceptable in ad campaigns in this phase, we strongly advise against using the legacy geo entities because the backend will convert them to new geo entities.
  3. To get the name for a Bing geo location, by the start of phase 2, Partners should have completed the changes to invoke urn-to-name resolver API. Refer to this example.
  4. What happens to the existing campaigns already created with legacy geo entities?
    1. Intelligent mapping: Where possible, LinkedIn will map existing campaign legacy locations to Bing geo gradually. Due to this if you do GET on campaign data, you may expect Bing location values from past campaigns. For example, if a campaign targets on urn:li:state:(urn:li:country:us,CA), LinkedIn will transform it to urn:li:geo:102095887 in the campaign’s targeting value.
    2. Entity name or audience count change after migration: In scenarios where LinkedIn doesn’t find the exact match for the legacy location, newly mapped Bing locations could be of a different name or higher/lower audience count.
    3. However, in some cases, where the legacy geo entity cannot be mapped to the new geo entity, we will notify you with suggested mapping. It will not affect creating a campaign or running campaign and no action is needed.

Examples of legacy geo name change to Bing geo name

Legacy Geo URN Legacy Geo Name Bing Geo URN Bing Geo Name
urn:li:countryGroup:LA Latin America urn:li:geo:104514572 South America
urn:li:country:kr Korea urn:li:geo:105149562 South Korea
urn:li:country:om Sultanate of Oman urn:li:geo:103619019 Oman
urn:li:country:vg Virgin Islands (British) urn:li:geo:105534858 British Virgin Islands
urn:li:country:vi Virgin Islands (U.S.) urn:li:geo:102119762 US Virgin Islands
urn:li:state:(urn:li:country:ch,ZH) Canton of Zürich urn:li:geo:102436504 Zurich
urn:li:state:(urn:li:country:pk,3) NWFP Peshawar urn:li:geo:106436446 Khyber Pakhtunkhwa
urn:li:state:(urn:li:country:cn,NX) Ningxia urn:li:geo:105325976 Ningxia Hui
urn:li:region:275 Destin/Fort Walton Beach, Florida Area urn:li:geo:90009453 Crestview-Fort Walton Beach-Destin Area
urn:li:region:928 York, Pennsylvania Area urn:li:geo:105243172 York County

Examples of legacy geo audience count change to bing geo audience count

Legacy Geo URN Legacy Geo Name Legacy Member count Bing Geo URN Bing Geo Name Bing Member Count Audience Change
urn:li:countryGroup:na North America 196514894 urn:li:geo:102221843 North America 218809397 11.34%
urn:li:countryGroup:LA Latin America 100608115 urn:li:geo:104514572 South America 78276886 11.34%
urn:li:countryGroup:AS Asia 178219309 urn:li:geo:102393603 Asia 204540435 14.77%
urn:li:countryGroup:ME Middle East 25967989 urn:li:geo:91000001 Middle East 33513746 29.06%
urn:li:state:(urn:li:country:pk,3) NWFP Peshawar 171048 urn:li:geo:106436446 Khyber Pakhtunkhwa 157474 -7.94%
urn:li:region:928 York, Pennsylvania Area 149810 urn:li:geo:105243172 York County 138636 -7.46%

Example of number of segments for legacy location to Bing geo entity segments

The reason for North America and South America change is because Mexico and a few island countries that are previously counted as part of Latin America, are now part of North America. A similar case of audience cover increases in Asia and the Middle East.

Legacy Geo URN Legacy Geo Name Legacy Member count Bing Geo URN Bing Geo Name Bing Member Count Audience Change
urn:li:region:5096 Pamplona Area, Spain 177535 urn:li:geo:100146939 urn:li:geo:102688677 Chartered Community of Navarre, Spain Guipúzcoa, Basque Country, Spain 228756 29%
urn:li:region:b6 Picardy 271597 urn:li:geo:107080171 urn:li:geo:102672257 urn:li:geo:105012670 Somme, Hauts-de-France, France, Oise, Hauts-de-France, France, Aisne, Hauts-de-France, France 272357 0.3%

One segment to multiple segments mapping is mostly for regions and a small part of states, and it will happen in phase 2 starting from Jan 2020.

Examples of same geographic name across different hierarchy from typeahead API

Search for San Jose Location-example-san-jose

Search for Georgia, the first response value is for the country in Europe. Location-example-georgia

During phase 2, the typeahead endpoint response will return Bing geo locations as shown in this example.

Also it opens up new entities that do not exist in legacy geo values:

REQUEST:

GET
https://api.linkedin.com/v2/adTargetingEntities?q=typeahead&query=san%20mate&facet=urn%3Ali%3AadTargetingFacet%3Alocations&queryVersion=QUERY_USES_URNS&locale.language=en&locale.country=US&lixEntity=urn%3Ali%3AsponsoredAccount%3A517969629

RESPONSE:

{
    "elements": [
        {
            "urn": "urn:li:geo:104739033",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "San Mateo County, California, United States"
        },
        {
            "urn": "urn:li:geo:104871069",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "San Mateo Atenco, México, Mexico"
        },
    ]
}

Note in the result the urn types and values have changed, names may be different from legacy name. There is no action required for developer at this step, the difference is that now Bing geo values(urn:li:geo:{id}) are returned in the result instead of legacy values(urn:li:countryGroup|country|state|region:{id}).

Migration Phase 3: Sunset of Legacy Geo locations in Ad campaigns

Phase 3 of migration starts from 4/1/2020.

Steps for Phase 3

  1. No action required if phase 2 migration steps are completed.
  2. campaign creation will accept ONLY Bing geo locations.
  3. While reading a campaign created with Bing geo locations, the location value will be: urn:li:geo:{id}. To get the name of Bing geo location, Partners need to invoke the urn-to-name resolver API. Please refer to this example.
  4. Create Ad campaign API will return an error response if any legacy locations are used for targeting.
  5. Any existing campaign using a legacy location should be automatically mapped to Bing geo location.

API Examples

Retrieve legacy locations using legacy geo API

REQUEST:

GET https://api.linkedin.com/v2/countryGroups

RESPONSE:

{
  "elements": [
    {
      "name": {
        "locale": {
          "country": "US",
          "language": "en"
        },
        "value": "Africa"
      },
      "$URN": "urn:li:countryGroup:AF",
      "countryGroupCode": "AF"
    },
    {
      "name": {
        "locale": {
          "country": "US",
          "language": "en"
        },
        "value": "Antarctica"
      },
      "$URN": "urn:li:countryGroup:AQ",
      "countryGroupCode": "AQ"
    },
    ...
  ],
  "paging": {
    "count": 10,
    "start": 0,
    "links": []
  }
}

Retrieve legacy locations using typeahead API

REQUEST

GET https://api.linkedin.com/v2/adTargetingEntities?q=TYPEAHEAD&facet=urn:li:adTargetingFacet:locations&query=afri

RESPONSE

{
    "elements": [
        {
            "urn": "urn:li:countryGroup:AF",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "Africa"
        },
        {
            "urn": "urn:li:country:za",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "South Africa"
        },
    ...
    ]
}

Retrieve Bing Geo locations using typeahead API

REQUEST

GET https://api.linkedin.com/v2/adTargetingEntities?q=TYPEAHEAD&facet=urn:li:adTargetingFacet:locations&query=afri

RESPONSE

{
    "elements": [
        {
            "urn": "urn:li:geo:103537801",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "Africa"
        },
        {
            "urn": "urn:li:geo:104035573",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "South Africa"
        },
    ...
    ]
}

Another example when querying a country

GET https://api.linkedin.com/v2/adTargetingEntities?q=TYPEAHEAD&facet=urn:li:adTargetingFacet:locations&query=Santa%20Clara

RESPONSE

{
    "elements": [
        {
            "urn": "urn:li:geo:105416315",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "Santa Clara County"
        },
    ...
    ]
}

Create Ad campaigns using Legacy Locations

POST https://api.linkedin.com/v2/adcampaignsV2

RESPONSE

{
    "account": "urn:li:sponsoredAccount:518121035",
    "audienceExpansionEnabled": false,
    "costType": "CPC",
    "creativeSelection": "OPTIMIZED",
    "dailyBudget": {
        "amount": "18",
        "currencyCode": "USD"
    },
    "locale": {
        "country": "US",
        "language": "en"
    },
    "name": "campaign Sponsored update B",
    "offsiteDeliveryEnabled": false,
    "runSchedule": {
        "end": 1529778043445,
        "start": 1528914043445
    },
    "targetingCriteria": {
        "include": {
            "and": [
                {
                    "or": {
                        "urn:li:adTargetingFacet:locations": [
                            "urn:li:region:84"
                        ]
                    }
                }
            ]
        }
    },
    "type": "SPONSORED_UPDATES",
    "unitCost": {
        "amount": "15",
        "currencyCode": "USD"
    },
    "status": "ACTIVE"
}

Create Ad campaigns using Bing Geo Locations

POST https://api.linkedin.com/v2/adcampaignsV2

RESPONSE

{
    "account": "urn:li:sponsoredAccount:518121035",
    "audienceExpansionEnabled": false,
    "costType": "CPC",
    "creativeSelection": "OPTIMIZED",
    "dailyBudget": {
        "amount": "18",
        "currencyCode": "USD"
    },
    "locale": {
        "country": "US",
        "language": "en"
    },
    "name": "campaign Sponsored update B",
    "offsiteDeliveryEnabled": false,
    "runSchedule": {
        "end": 1529778043445,
        "start": 1528914043445
    },
    "targetingCriteria": {
        "include": {
            "and": [
                {
                    "or": {
                        "urn:li:adTargetingFacet:locations": [
                            "urn:li:geo:102095887"
                        ]
                    }
                }
            ]
        }
    },
    "type": "SPONSORED_UPDATES",
    "unitCost": {
        "amount": "15",
        "currencyCode": "USD"
    },
    "status": "ACTIVE"
}

Use of urn-to-name resolver API

Get the name of the Legacy geo location values

Encoded Request

GET https://api.linkedin.com/v2/adTargetingEntities?q=urns&urns=List({encoded urn:li:state:(urn:li:country:us,CA)},{encoded urn:li:region:82})&locale=(language:en,country:US)

Unencoded Request

GET https://api.linkedin.com/v2/adTargetingEntities?q=urns&queryVersion=QUERY_USES_URNS&urns=List(urn%3Ali%3Astate%3A%28urn%3Ali%3Acountry%3Aus%2CCA%29,urn%3Ali%3Aregion%3A82)&locale=(language:en,country:US)

Response

{
    "elements": [
        {
            "urn": "urn:li:state:(urn:li:country:us,CA)",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "California"
        },
        {
            "urn": "urn:li:region:82",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "Sacramento, California Area"
        }
    ],
    "paging": {
        "count": 2147483647,
        "links": [],
        "start": 0
    }
}

Get the name of the new Bing geo location values

Encoded Request

GET https://api.linkedin.com/v2/adTargetingEntities?q=urns&urns=List({encoded urn:li:geo:102095887},{encoded urn:li:geo:101857797})&locale=(language:en,country:US)

Unencoded Request

GET https://api.linkedin.com/v2/adTargetingEntities?q=urns&queryVersion=QUERY_USES_URNS&urns=List(urn%3Ali%3Ageo%3A102095887,urn%3Ali%3Ageo%3A101857797)&locale=(language:en,country:US)

Response

{
  "elements": [
    {
      "urn": "urn:li:geo:102095887",
      "facetUrn": "urn:li:adTargetingFacet:locations",
      "name": "California, United States"
    },
    {
      "urn": "urn:li:geo:101857797",
      "facetUrn": "urn:li:adTargetingFacet:locations",
      "name": "Sacramento, California, United States"
    }
  ],
  "paging": {
    "count": 2147483647,
    "links": [],
    "start": 0
  }
}

Frequently Asked Questions (FAQs)

  1. When are legacy geo locations values going to be deprecated? What are the corresponding Bing geo location values?
    • Legacy geo locations will be deprecated for non LMS use cases at a future date. The exact timeline will be released as we come to know. Beginning from phase 3, Ads targeting won't accept legacy geo locations in campaign creation. Legacy values examples: urn:li:countryGroup:{id},urn:li:country:{id},urn:li:state:{id},urn:li:region:{id} and corresponding examples in Bing geo are: urn:li:geo:{id}.
  2. How to get the localized name of the new Bing geo location values?
    • To get the localized name for a Bing geo location, invoke the urn-to-name resolver endpoint. Both legacy and Bing geo values are supported in the same API. Refer to this example.
  3. How to display all Bing geo location names for my active campaign:
    • Retrieve campaign info with a finder or an id.
  4. How to display search location result on load
    • LinkedIn campaign Manager will switch from legacy geo APIs to typeahead in Sep 2019. With that users of campaign Manager will no longer see a list of continents on first load but rather a blank search box. The locations will start populating results as user types the locations. Treeview display will no longer be shown.
    • Partners should show an empty search box and only show results as user enters search text
  5. Can I use both legacy and new Bing geo in same campaign?
    • Yes, starting from phase 2, an ad campaign can include both legacy and Bing locations. For example: campaign can target both urn:li:geo:90000084 and urn:li:region:4573 in the same campaign. But from phase 3 only Bing geo locations are accepted in campaign creation.
  6. I have stored the created campaign locally in my own system, is there anything I need to pay attention?
    • Yes. During/after phase 2, the legacy values are updated by LinkedIn to new Bing geo values, so when GET the previously created campaigns, the values will be different from when it was stored. It is suggested to overwrite local stored values if necessary.
  7. When can I begin migration to typeahead finder and urn-to-name resolver API for geo entities?
    • Beginning from Phase 1, you can start using the Ads targeting typeahead finder and urn-to-name resolver API for legacy geo entities. And from phase 2, typeahead will return Bing geo locations. urn-to-name resolver API will always support legacy and Bing geo locations.
  8. By what date will my app break if I don’t take any action now?
    • We expect all our API partners to complete Phase 1 and Phase 2 by end of Mar 2020 and ramp new Bing geo entities. We highly recommend migrating as per our proposed phases as we will be able to support your needs better. Beginning of Phase 3, if none of the actions were taken from previous phases, create campaign will break if legacy geo locations are used.
  9. When will the old location APIs be deprecated? What if I don't migrate?
    • The legacy locations API may be used in use cases other than Ads Targeting. The timeline for deprecating legacy locations for non-targeting uses cases is not yet decided. However, we require Ads API partners to align with this migration timeline, as after phase 2 migration, campaign creation will not take legacy geo entities even if the legacy locations API has not been deprecated for other use cases by that time.
  10. When will LinkedIn start ramping Bing geo (migration phase 2)?
    • Linkedin Ads will start to ramp Bing geo after phase 1 around 12/12/2019.
  11. By what date will the app break if migration phase 2 not completed?
    • We expect phase 2 migration to be complete by 3/31/2020. After that, legacy geo entities will not be supported any more in LinkedIn ads system and exception will be thrown if legacy geo entities are passed in to create campaign.
  12. How will we be able to distinguish between the two locations names with the same name?
    • Typeahead API will provide metadata on the immediate parent to that geo (Georgia - United States vs. Georgia - Europe)
  13. When will shares/ugc targeting locations migrate to Bing geo?
    • The timeline for shares and ugc legacy locations migration to Bing geo has not been determined yet. LinkedIn will inform partners when the plan to kick off the migration is clear.