Organic Company UGC and Share Targeting Bing Geo Migration Guide

  • Article

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.

This migration guide provides the details of migrating from current geo endpoints/values to the new ones.

These steps should be performed prior to Sept 30, 2021.

For targeting locations, LinkedIn Bing geo. If you are a partner using LinkedIn legacy locations (Country, CountryGroup, Region, State) to create organic (non-sponsored) targeted company posts using UGC TargetAudience or Share linkedInDistributionTarget APIs, please continue reading this guide.

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 the US.

Important

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.

Permissions

Permission Description
r_organization_social Retrieve organizations' posts, comments, and likes. Restricted to organizations in which the authenticated member has one of the following company page roles.
  • ADMINISTRATOR
  • DIRECT_SPONSORED_CONTENT_POSTER

See Organization Access Control for more information on company page roles.

Migration Steps

  1. Migrate
  • From hard-coded legacy location urn or legacy location API to new Bing Geo Typeahead API to retrieve corresponding bing geo urn of locations that you want to target for an organic company post.
  1. Start using Bing geo urns
  • Retrieved from Geo Typeahead API in geoLocations field instead of locations field for organic company post targeting. Only bing geoLocations will be accepted after Sept 30th, 2021. Legacy locations can no longer be used for organic targeted company post after Sept 30th, 2021.

1. Migrate to new Bing Geo Typeahead

Geo Typeahead API from legacy location API or hard-coded legacy location URN

LinkedIn now enforces partners to use the Geo Typeahead API to retrieve geo urns of locations to be targeted instead of using hard coded legacy location urns (eg. country, countryGroup, state, region urns) or legacy location APIs for organic company post targeting.

  1. Partners have 3 months starting from 6/30/2021 to 09/30/2021 to migrate from using legacy location APIs or hard coded legacy location urns to new Bing Geo typeahead API to retrieve Bing geo urns and use that in the new geoLocations field for organic company post targeting.
  2. Between 6/30/2021 to 09/30/2021, both legacy location urn (eg. countryGroup, country, region, state urns) in locations field and geo urn in geoLocations field are accepted for UGC and Share APIs.

Example using legacy Location APIs

How to use the Bing Geo Typeahead

Bing Geo Typeahead API provides a list of Bing Geo urns based on user-provided text input.

Bing Geo Typeahead Sample Requests
GET https://api.linkedin.com/rest/geoTypeahead?q=search&query=united

GET https://api.linkedin.com/rest/geoTypeahead?q=search&query=united&locale=(language:en,country:US)

GET https://api.linkedin.com/v2/geoTypeahead?q=search&query=united

GET https://api.linkedin.com/v2/geoTypeahead?q=search&query=united&locale=(language:en,country:US)
Bing Geo Typeahead Sample Response
{
    "paging": {
        "start": 0,
        "count": 10,
        "links": [
            {
                "type": "application/json",
                "rel": "next",
                "href": "/v2/geoTypeahead?q=search&query=united&count=10&start=10"
            }
        ],
        "total": 0
    },
    "elements": [
        {
            "displayText": "United States",
            "entity": "urn:li:geo:103644278"
        },
        {
            "displayText": "United Kingdom",
            "entity": "urn:li:geo:101165590"
        },
        {
            "displayText": "United Arab Emirates",
            "entity": "urn:li:geo:104305776"
        },
        {
            "displayText": "England, United Kingdom",
            "entity": "urn:li:geo:102299470"
        },
        {
            "displayText": "California, United States",
            "entity": "urn:li:geo:102095887"
        },
        {
            "displayText": "Texas, United States",
            "entity": "urn:li:geo:102748797"
        },
        {
            "displayText": "New York, United States",
            "entity": "urn:li:geo:105080838"
        },
        {
            "displayText": "Florida, United States",
            "entity": "urn:li:geo:101318387"
        },
        {
            "displayText": "London Area, United Kingdom",
            "entity": "urn:li:geo:90009496"
        },
        {
            "displayText": "London, England, United Kingdom",
            "entity": "urn:li:geo:102257491"
        }
    ]
}

2. Use Bing Geo locations for Organic Company Post Targeting

In Step 2, partners start to populate geoLocations field with new bing geo urns retrieved from the new Geo Typeahead API.

Timeline

  • June 30th, 2021 - Sept 30th, 2021: Both locations field with legacy location urns and geoLocations field with new Bing Geo urns are supported.
  • On Sept 30th, 2021: locations field will be deprecated and UGC and Share APIs will reject any request with the deprecated locations field. Only geoLocations field with Bing Geo urns populated is supported.
  • After Sept 30th, 2021, if locations field is used, UGC and Share API will return following error response below.
{
    "message": "com.linkedin.content.common.ResponseException: Target 'locations' field is deprecated. Please use 'geoLocations' field instead",
    "status": 400
}

Details

  1. Partners migrate to use new geoLocations field with Bing Geo urns instead of locations field with legacy location urns for targeting organic post/share to specific locations. Please refer to UGC and Share sample creation requests with geoLocations field for examples.
  2. What happens to the organic targeted company posts/shares already created with legacy location urns in locations field prior to Sept 30th, 2021?
    1. No action needed from Partners. LinkedIn will run a data fix on Sept 30th, 2021 where it will automatically populate geoLocations with corresponding geo urns from legacy location urns from locations field and locations fields are removed.
  3. As there is no direct 1 to 1 mapping between legacy location urn and new bing geo urn, target count for organic targeted company share/post with new Bing Geo urns and information (eg. name) on some locations might differ a little bit as shown below.

Examples of legacy location name change to Bing geo name

Legacy Location URN Legacy Location 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 location audience count change to bing geo audience count

Legacy Location URN Legacy Location Name Legacy Total Member count Bing Geo URN Bing Geo Name Bing Total 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 -22.19%
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 Location URN Legacy Location 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%

Sample Creation Requests for UGC and Share for old locations field and new geoLocations field

Old requests use country urn urn:li:country:us in the legacy locations field whereas new requests use bing geo urn urn:li:geo:103644278 (which is a corresponding geo urn for country urn urn:li:country:us) in the new geoLocations field.

Sample Organic Targeted Company UGC Post creation request with legacy locations field

POST https://api.linkedin.com/rest/ugcPosts

{
    "author": "urn:li:organization:5590506",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "media": [
                {
                    "media": "urn:li:digitalmediaAsset:C5500AQG7r2u00ByWjw",
                    "status": "READY",
                    "title": {
                        "attributes": [],
                        "text": "Sample Video Create"
                    }
                }
            ],
            "shareCommentary": {
                "attributes": [],
                "text": "Some share text"
            },
            "shareMediaCategory": "VIDEO"
        }
    },
    "targetAudience": {
        "targetedEntities": [
            {
                "locations": [
                    "urn:li:country:us"
                ],
                "seniorities": [
                    "urn:li:seniority:3"
                ]
            }
        ]
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}

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

{
    "author": "urn:li:organization:5590506",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "media": [
                {
                    "media": "urn:li:digitalmediaAsset:C5500AQG7r2u00ByWjw",
                    "status": "READY",
                    "title": {
                        "attributes": [],
                        "text": "Sample Video Create"
                    }
                }
            ],
            "shareCommentary": {
                "attributes": [],
                "text": "Some share text"
            },
            "shareMediaCategory": "VIDEO"
        }
    },
    "targetAudience": {
        "targetedEntities": [
            {
                "locations": [
                    "urn:li:country:us"
                ],
                "seniorities": [
                    "urn:li:seniority:3"
                ]
            }
        ]
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}

Sample Organic Targeted Company UGC Post creation request with new geoLocations field

POST https://api.linkedin.com/rest/ugcPosts

{
    "author": "urn:li:organization:5590506",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "media": [
                {
                    "media": "urn:li:digitalmediaAsset:C5500AQG7r2u00ByWjw",
                    "status": "READY",
                    "title": {
                        "attributes": [],
                        "text": "Sample Video Create"
                    }
                }
            ],
            "shareCommentary": {
                "attributes": [],
                "text": "Some share text"
            },
            "shareMediaCategory": "VIDEO"
        }
    },
    "targetAudience": {
        "targetedEntities": [
            {
                "geoLocations": [
                    "urn:li:geo:103644278"
                ],
                "seniorities": [
                    "urn:li:seniority:3"
                ]
            }
        ]
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}

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

{
    "author": "urn:li:organization:5590506",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "media": [
                {
                    "media": "urn:li:digitalmediaAsset:C5500AQG7r2u00ByWjw",
                    "status": "READY",
                    "title": {
                        "attributes": [],
                        "text": "Sample Video Create"
                    }
                }
            ],
            "shareCommentary": {
                "attributes": [],
                "text": "Some share text"
            },
            "shareMediaCategory": "VIDEO"
        }
    },
    "targetAudience": {
        "targetedEntities": [
            {
                "geoLocations": [
                    "urn:li:geo:103644278"
                ],
                "seniorities": [
                    "urn:li:seniority:3"
                ]
            }
        ]
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}

Sample Organic Targeted Company Share creation request with legacy locations field

POST https://api.linkedin.com/rest/shares

{
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "title": "Test Share with Content !!"
    },
    "distribution": {
        "externalEntities": [],
        "linkedInDistributionTarget": {
            "industries": [
                "urn:li:industry:4"
            ],
            "locations": [
                "urn:li:country:us"
            ],
            "seniorities": [
                "urn:li:seniority:3"
            ]
        }
    },
    "owner": "urn:li:organization:2414183",
    "subject": "Test Share Subject !!",
    "text": {
        "text": "Test Share created by postman !!"
    }
}

Sample Organic Targeted Company Share creation request with new geoLocations field

POST https://api.linkedin.com/rest/shares

{
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "title": "Test Share with Content !!"
    },
    "distribution": {
        "externalEntities": [],
        "linkedInDistributionTarget": {
            "industries": [
                "urn:li:industry:4"
            ],
            "geoLocations": [
                "urn:li:geo:103644278"
            ],
            "seniorities": [
                "urn:li:seniority:3"
            ]
        }
    },
    "owner": "urn:li:organization:2414183",
    "subject": "Test Share Subject !!",
    "text": {
        "text": "Test Share created by postman !!"
    }
}

Sample Organic Targeted Company Share creation request with legacy locations field

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

{
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "title": "Test Share with Content !!"
    },
    "distribution": {
        "externalEntities": [],
        "linkedInDistributionTarget": {
            "industries": [
                "urn:li:industry:4"
            ],
            "locations": [
                "urn:li:country:us"
            ],
            "seniorities": [
                "urn:li:seniority:3"
            ]
        }
    },
    "owner": "urn:li:organization:2414183",
    "subject": "Test Share Subject !!",
    "text": {
        "text": "Test Share created by postman !!"
    }
}

Sample Organic Targeted Company Share creation request with new geoLocations field

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

{
    "content": {
        "contentEntities": [
            {
                "entityLocation": "https://www.example.com/content.html",
                "thumbnails": [
                    {
                        "resolvedUrl": "https://www.example.com/image.jpg"
                    }
                ]
            }
        ],
        "title": "Test Share with Content !!"
    },
    "distribution": {
        "externalEntities": [],
        "linkedInDistributionTarget": {
            "industries": [
                "urn:li:industry:4"
            ],
            "geoLocations": [
                "urn:li:geo:103644278"
            ],
            "seniorities": [
                "urn:li:seniority:3"
            ]
        }
    },
    "owner": "urn:li:organization:2414183",
    "subject": "Test Share Subject !!",
    "text": {
        "text": "Test Share created by postman !!"
    }
}

Bing Geo Frequently Asked Questions

  1. When are legacy locations values (eg. country, countryGroup, region and state) going to be deprecated? What are the corresponding Bing geo location values?
    • Legacy locations will be deprecated for organic company post targeting on Sept 30th, 2021. Corresponding Bing geo urn can be retrieved using Geo Typeahead API
  2. What happens to old posts with legacy location urns in locations field?
    • LinkedIn will take care of that part where it will run a data fix on Sept 30th, 2021 to populate corresponding geo urns in geoLocations field based on legacy location urns in locations and remove existing locations field.
  3. What happens to existing target audience count restriction for Organic Company Post targeting?