Marketing Analytics Getting Started

LinkedIn's Marketing Analytics APIs enable you to leverage LinkedIn marketing data to automate internal reporting and gain valuable insights. Partners can integrate LinkedIn data into their solutions to retrieve performance data, targeting information, audience insights, and much more. This guide provides a brief look at how these APIs can be used to provide valuable insights into audiences, impressions, targeting, and budgeting data.

For a better picture of what the platform fully provides in functionality, read the Overview page or Ad Tech Getting Started.

Permissions

Whether set as a default permission in your app settings or requested specifically via the scope argument during your authentication process, you will need to request the r_ads member permission in order for your application to successfully make these API calls to LinkedIn.

Audience Counts

The audienceCountsV2 API allows you to forecast reach based on targeting criteria.

Sample Request

The following request returns estimated audience counts for Canada and USA while excluding members who are in entry-level positions.

GET https://api.linkedin.com/v2/audienceCountsV2?q=targetingCriteria&target.includedTargetingFacets.locations[0]=urn:li:country:ca&target.includedTargetingFacets.locations[1]=urn:li:country:us&target.excludingTargetingFacets.seniorities[0]=urn:li:seniority:3

Sample Response

{
    "elements": [
        {
            "active": 0,
            "total": 150000000
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

See the targetingFacets reference page to learn more about targetingFacets and Audience Counts for more information on the Audience Counts API.

Ad Budget Pricing

With the adBudgetPricing API, you can get key insights on pricing metrics such as minimum, maximum, and suggested bids based on targeting criteria. The sample request returns pricing for an account based on target market criteria.

Sample Request

In the following example, the target market consists of LinkedIn members between the ages of 18 and 24.

GET https://api.linkedin.com/v2/adBudgetPricing?account=urn:li:sponsoredAccount:1245678&bidType=CPM&campaignType=SPONSORED_INMAILS&matchType=EXACT&q=criteria&target.includedTargetingFacets.ageRanges[0]=AGE_18_24

Sample Response

{
    "elements": [
        {
            "maxBid": {
                "amount": "100.0",
                "currencyCode": "USD"
            },
            "minBid": {
                "amount": "0.3",
                "currencyCode": "USD"
            },
            "suggestedBid": {
                "amount": "2.06",
                "currencyCode": "USD"
            },
            "suggestedBidRangeHighEnd": {
                "amount": "2.11",
                "currencyCode": "USD"
            },
            "suggestedBidRangeLowEnd": {
                "amount": "2.01",
                "currencyCode": "USD"
            }
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

See the targetingFacets reference page to learn more about targetingFacets and Ad Budget Pricing for more information on the Ad Budget Pricing API.

Ad Supply Forecasts

The adSupplyForecasts API provides impression and budget data based on target set, bid, and time period.

Sample Request

The following sample request forecasts the impressions of a sponsored update for Canada and USA while excluding members in entry-level positions.

GET https://api.linkedin.com/v2/adSupplyForecasts?q=criteria&timeRange.start=1464804127000&timeRange.end=1465581727000&target.includedTargetingFacets.locations[0]=urn:li:country:ca&target.includedTargetingFacets.locations[1]=urn:li:country:us&target.excludingTargetingFacets.seniorities[0]=urn:li:seniority:3&campaignType=SPONSORED_UPDATES&competingBid.bidType=CPM&competingBid.bidPrice.currencyCode=USD&competingBid.bidPrice.amount=10

Sample Response

{
  "elements": [
    {
      "timeSeries": [
        {
          "value": 22874,
          "timestamp": 1485302400000
        },
        {
          "value": 2244802,
          "timestamp": 1485388800000
        },
        {
          "value": 1869223,
          "timestamp": 1485475200000
        },
        {
          "value": 1098326,
          "timestamp": 1485561600000
        },
        ...
     ],
     "metricType": "IMPRESSION",
      "granularity": "DAILY"
    }
  ],
  "paging": {
    "count": 10,
    "start": 0,
    "links": []
  }
}

For more information on the Ad Supply Forecasts API, check out Ad Supply Forecasts.

Suggested Targeting Options

The LinkedIn Ads platform allows you to reach a wide range of audiences based on unique targeting criteria. The Ad Targeting Similar Entities finder suggests additional targeting attributes based on a provided target set.

Sample Request

The following example returns industries similar to Biotechnology, urn:li:industry:12. To improve readability, the projection parameter adds the industry name to the API response.

GET https://api.linkedin.com/v2/adTargetingEntities?q=similarEntities&facet=urn:li:adTargetingFacet:industries&entityType=INDUSTRY&entities=urn:li:industry:12&projection=(elements*(value(string~(name))))

Sample Response

{
  "elements": [
    {
      "value": {
        "string": "urn:li:industry:15",
        "string~": {
          "name": {
            "localized": {
              "en_US": "Pharmaceuticals"
            }
          }
        }
      }
    },
    {
      "value": {
        "string": "urn:li:industry:17",
        "string~": {
          "name": {
            "localized": {
              "en_US": "Medical Device"
            }
          }
        }
      }
    },
    {
      "value": {
        "string": "urn:li:industry:13",
        "string~": {
          "name": {
            "localized": {
              "en_US": "Medical Practice"
            }
          }
        }
      }
    },
    ...
  ]
}

To learn more about Targeting by Similar Entities, see the Ad Targeting page.

Updating a Share with UTM Tracking Parameters

URLs in shares can be updated to include UTM parameters for advertisers to track the success of marketing efforts and prove ROI. This feature allows retroactive modification of URLs contained within shares.

To update UTM parameters, you must know the share URN and content of the share. For more information on how to leverage this feature, see UTM Tracking.

POST https://api.linkedin.com/v2/sharesUrl/{shareURN}
{
    "patch": {
        "content": {
            "$set": {
                "contentEntities": [
                    {
                        "description": "News, email and search are just the beginning. Discover more every day. Find your yodel.",
                        "entity": "urn:li:article:8302773461016502828",
                        "entityLocation": "https://www.yahoo.com?utm_campaign=blogpost&utm_medium=social&utm_source=facebook",
                        "thumbnails": [
                            {
                                "imageSpecificContent": {
                                    "height": 200,
                                    "size": 5992,
                                    "width": 200
                                },
                                "resolvedUrl": "https://s.yimg.com/dh/ap/default/130909/y_200_a.png"
                            }
                        ],
                        "title": "Test Share with Content !!"
                    }
                ]
            }
        }
    }
}

Ad Analytics

The Ad Analytics API provides account, campaign, and creative level statistics on current spend as well as chargeable clicks and impressions. To learn more, see Ads Reporting.

Sample Request

The following example returns analytics from January 1, 2016 for campaign ID 10002907 with a monthly time granularity and pivoting based on creatives.

GET https://api.linkedin.com/v2/adAnalyticsV2?q=analytics&dateRange.start.month=1&dateRange.start.day=1&dateRange.start.year=2016&timeGranularity=MONTHLY&pivot=CREATIVE&campaigns=urn:li:sponsoredCampaign:112466001

Sample Response

{
    "elements": [
        {
            "chargeableClicks": 59,
            "dateRange": {
                "end": {
                    "day": 18,
                    "month": 9,
                    "year": 2016
                },
                "start": {
                    "day": 1,
                    "month": 1,
                    "year": 2016
                }
            },
            "impressions": 8456,
            "nonchargeableClicks": 1,
            "pivot": "urn:li:sponsoredCampaign:10002907",
            "spend": {
                "amount": "142.00",
                "currencyCode": "USD"
            }
        }
    ],
    "paging": {
        "count": 10,
        "start": 0
    }
}

Share & Social Action Insights

Share and Social Action APIs provide insights into share, like, and comment statistics. This data can be used to optimize organic and sponsored content performance.

Find Share by URN

GET https://api.linkedin.com/v2/shares/{share URN}

Sample Response

{
    "activity": "urn:li:activity:6230438468758052864",
    "content": {
        "contentEntities": [
            {
                "entity": "urn:li:article:6994272117874578221",
                "entityLocation": "http://www.lemondeinformatique.fr/actualites/lire-business-france-emmene-des-start-ups-au-web-summit-de-lisbonne-66405.html?utm_source=Sociallymap&utm_medium=Sociallymap&utm_campaign=Sociallymap"
            }
        ],
        "description": "8 start-ups fran\u00e7aises IT ont \u00e9t\u00e9 s\u00e9lectionn\u00e9es parmi 60 candidates par la d\u00e9l\u00e9gation Business France pour participer au Web Summit 2016 qui aura...",
        "title": "Business France emm\u00e8ne des start-ups au Web Summit de Lisbonne - Le Monde Informatique"
    },
    "created": {
        "actor": "urn:li:person:uex10Z3oFO",
        "time": 1485452286000
    },
    "distribution": {
        "linkedInDistributionTarget": {}
    },
    "edited": false,
    "id": "6230438468804177920",
    "lastModified": {
        "actor": "urn:li:person:uex10Z3oFO",
        "time": 1485452286000
    },
    "owner": "urn:li:organization:2414183",
    "text": {
        "text": "Business France emm\u00e8ne des start-ups au Web Summit de Lisbonne #airmisconseil"
    }
}

Social Actions

Shares may have social actions such as likes and comments attached to them. With the socialActions API, you can view social actions on various types of network updates. To learn more about retrieving social actions, see Network Update Social Action.

Find Comments for a Share

GET https://api.linkedin.com/v2/socialActions/{share URN}/comments

Sample Response

{
    "elements": [
        {
            "created": {
                "time": 1485303622383
            },
            "id": "6229814924525211648",
            "lastModified": {
                "time": 1485303622383
            },
            "message": {
                "attributes": [],
                "text": "This is a comment"
            },
            "object": "urn:li:activity:6229788468420055040"
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

Find Likes for a Share

GET https://api.linkedin.com/v2/socialActions/{share URN}/likes

Sample Response

{
    "elements": [
        {
            "created": {
                "time": 1485303834338
            },
            "lastModified": {
                "time": 1485303834515
            },
            "object": "urn:li:activity:6229788468420055040"
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}