Use Python and Brightlocal API to Grab Your Keyword Rankings

Brightlocal has been in the SEO toolbox for local ranking and citations for a number of years now.  Brightlocal has an extensive API system allowing you to retrieve info and automate a lot of processes. In this tutorial, I’m going to show you how it easy is to grab your ranking data from their API using Python. Brightlocal API is paid but they give you 1000 calls for free (they say for testing). That may seem like a lot, but multiple calls are often required to get the information we need, especially if you have many campaigns. Due to the proprietary nature of the data, I won’t be showing any example output.

Requirements and Assumptions

• Python 3 is installed and basic Python syntax understood
• Access to a Linux installation (I recommend Ubuntu) or Google Colab

Import Modules

• requests for the API calls
• json for data parsing
• pandas for data storage
• %load_ext google.colab.data_table is a colab pandas extension for better print out visuals

import requests 
import json
import pandas as pd
%load_ext google.colab.data_table

First, we need to set our API Key. You can find this in your Brightlocal account profile. Then we set an empty dataframe that will eventually store our keyword data.

Set API Key and Dataframe

apikey = "YOUR_API_KEY"
df = pd.DataFrame([], columns=['CID','Keyword','Current Google','Last Google'])

Next, we are ready to make our first API call. This call is to retrieve all the campaign IDs in your account which we’ll use in the second call to get the rankings for all the keywords each campaign is tracking. This will capture all the campaigns in your account. If you only want a select number, you can change this script to use a manual list of campaign IDs you put in and loop through those.

Setup First API Call

url = "https://tools.brightlocal.com/seo-tools/api/v2/lsrc/get-all?api-key=" + apikey 
payload = {} 
headers = {} 
response = requests.request("GET", url, headers=headers, data = payload) 
camids = json.loads(response.text.encode('utf8'))

Below takes the json response from the call above and builds the campaign ID list. There is also a counter that will print the number of campaigns in the list just if you were curious.

Build Campaign List

ids = []
counter = 0
getcam = camids["response"]["results"]
for i in getcam:
  ids.append(i["campaign_id"])
  counter = counter +1
print(ids)
print(str(counter) + " campaigns")

Next, we loop through the list of campaign IDs and make another API that returns the rankings for the keywords each campaign is tracking. Below we capture the current Google ranking and the previous Google rankings. It would be trivial to calculate a difference at this point. Also, note the JSON contains current and previous rankings for Microsoft Bing. Using what I have below you can easily add those in. The convention stays the same.

So kdata["response"]["result"]["rankings"]["rankings"][i]["bing"][0]["rank"] for current Microsoft Bing ranking.

Get Rankings

  for id in ids:
    url = "https://tools.brightlocal.com/seo-tools/api/v2/lsrc/results/get?api-key="+apikey+"&campaign-id=" + str(id)
    payload = {}
    headers = {}
    response = requests.request("GET", url, headers=headers, data = payload)

    kdata = json.loads(response.text.encode('utf8'))
    
    getkeywords = kdata["response"]["result"]["rankings"]["keywords"]

    for i in getkeywords:
      cgoogle = kdata["response"]["result"]["rankings"]["rankings"][i]["google"][0]["rank"]
      try:
        lgoogle =  kdata["response"]["result"]["rankings"]["rankings"][i]["google"][0]["last"]
      except:
        lgoogle = "n/a"

      keyword_dict = {"CID":id,"Keyword":i,"Current Google":cgoogle,"Last Google":lgoogle}
      df = df.append(keyword_dict, ignore_index=True)

df.head(25)

Conclusion

You can now see how easy it is to grab your keyword ranking data from Brightlocal API! From here you can automate, store and extend this script to grab more data or perform calculations. Please follow me on Twitter for feedback and showcasing interesting ways to extend the script. Enjoy!