Ads Targeting Migration Guide to Bing Geo

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

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 LinkedIn Marketing API 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/rest/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/regions
3. Get all states
4. Get all regions
5. Get all countries/regions 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/regions 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

Search for Georgia, the first response value is for the country in Europe.

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/rest/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/rest/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/rest/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/rest/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/rest/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/rest/adcampaigns

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": 9876543210123,
        "start": 1234567890987
    },
    "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/rest/adcampaigns

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": 9876543210123,
        "start": 1234567890987
    },
    "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/rest/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/rest/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/rest/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/rest/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. Tree view 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?
    • Share and UGC 'locations' fields will be deprecated on Sept 30th, 2021. Please use 'geoLocations' field for organic company post targeting.