APIs can often be quite intimidating for SEO professionals, especially for those more accustomed to working in Microsoft Excel. While Rank Ranger provides easy-to-follow documentation, I’ve written this guide to provide you with the Python code so that you can literally copy-paste the code to get started immediately.

The Rank Ranger API offers many capabilities from two main APIs:

• Reporting: managing and extracting data on clients you’re tracking data within your Rank Ranger account
• Search: competitive intelligence such as the SERPs with features

We’ll be focusing on getting data on your:

• Package ID number (required to get data from the rest of the API)
• Campaigns that you’re running
• Keywords (within a campaign)
• Rankings (for your keywords)

You’ll notice in each section there are quite a few steps that we explain to help you understand what the Python code is doing so you can learn a little Python on the way while appreciating mini-hurdles to be overcome in getting your data!

Preliminaries 

You can assume that all of the Python code will be run within a Jupyter notebook locally on your machine, however, the code should also run in Google colab notebooks also.

We start by importing our libraries:

import requests <br /> import pandas as pd <br /> import numpy as np <br /> import json

You’ll need your API token which is generated under Settings > API & Connected Apps to replace the fictitious API token below:

api_token = ‘12345-x1234abcd12345abcdefg0xyz1h2a3seo’

Package ID number 

Once the Python library packages are imported and the api token variable is set, we’re ready to start using the API:

First we build and make the request of which the result is saved to an object called ‘r’. The request ‘r’ is the API URL we called includes the API URL, the ‘packages’ API endpoint (highlighted in yellow), the api key and the output which is set to json:

r = requests.get(‘https://www.rankranger.com/api/v2/?packages&output=json&key=’ + api_token)

We print ‘r’ so we can see whether the API call managed to connect (or not):

print(r)

Below we get a 200 response which is a good sign:

<Response [200]>

Now we want to unpack the contents of the API response by using the ‘.text’ attribute of ‘r’ in combination with the pandas (pd) read_json() function. This will be saved into a new variable called ‘packages_output’:

packages_output = pd.read_json(r.text)

To make the json output parseable, we’ll convert it to a list using the to_list() function:

packages_list = packages_output[‘packages’].to_list()

Using print we can see what it looks like:

print(packages_list)

Example output is shown below with the package ID number highlighted:

[{‘id’: ‘87321’, ‘plan_name’: ‘Enterprise Brand Ambassador 2SE’, ‘start_date’: ’02-20-2023′, ‘status’: ‘Active (Included)’, ‘capacity’: {‘campaigns’: {‘used_campaigns’: ’48’, ‘total_campaigns’: ’50’}, ‘keywords’: {‘used_keywords’: ‘123456’, ‘total_keywords’: ‘123456’}}}]

Campaigns 

Once you have your Package ID which in the above example is printed out as ‘87321’, you can start seeing what campaigns you have to extract data from. We’ll start by setting the packages_id variable:

packages_id = ‘87321’

Then we’ll build the request, this time using the ‘package_campaigns’ endpoint:

r = requests.get(‘https://www.rankranger.com/api/v2/?package_campaigns&output=json&key=’ + api_token + ‘&package_id=’ + packages_id)

As before we’ll unpack the API response using read_json, convert to a list and print the results:

campaigns_output = pd.read_json(r.text) <br /> campaigns_list = campaigns_output[‘campaigns’].to_list() <br /> print(campaigns_list)

Again we have a fictitious list to demonstrate what the output would look like:

[[ <br /> {‘id’: ‘123456’, ‘name’: ‘Amazon US’, ‘domain’: ‘amazon.com’, ‘se_ids’: ‘1’}, <br /> {‘id’: ‘123457’, ‘name’: ‘Amazon UK’, ‘domain’: ‘amazon.co.uk’, ‘se_ids’: ’64’}, <br /> …, <br /> {‘id’: ‘123459’, ‘name’: ‘Slate Safety’, ‘domain’: ‘slatesafety.com’, ‘se_ids’: ‘1’} <br /> ]]

Note that the output lists all the campaigns by their campaign id, name, the domain and the search engine targeted.

Keywords 

Let’s get the keywords from the Slate Safety campaign which will use the get_campaign_info API endpoint and the desired campaign id set below:

campaigns_id = ‘123459’ <br /> r = requests.get(‘https://www.rankranger.com/api/v2/?get_campaign_info&output=json&key=’ + api_token + ‘&campaign_id=’ + campaigns_id + ‘&show_tags=true&include_rank_stats=true’) <br /> keywords_output = pd.read_json(r.text) <br /> print(keywords_output)

You’ll see from the keywords_output that you get all kinds of information such as the domain, number of keywords, the keywords themselves, domain, search engine etc:

result <br /> campaign_id 123459 <br /> campaign_manager {} <br /> campaign_name Slate Safety <br /> domains {‘domain’: ‘slatesafety.com’} <br /> industry {} <br /> keywords {‘keyword’: [{‘name’: ‘biometric device’, ‘tag… <br /> keywords_count 78 <br /> main_domain slatesafety.com <br /> package Enterprise Brand Ambassador 2SE <br /> portal {‘custom_url’: {}, ‘password’: {}, ‘direct_url… <br /> profile_name {} <br /> rank_stats {‘total_keywords’: ’78’, ‘total_search_engines… <br /> search_engines {‘se’: {‘id’: ‘1’, ‘name’: ‘Google USA’, ‘url’…

As usual, we’ll convert the output to a list:

keywords_list = keywords_output[‘result’].to_list()

Then to get the keywords we simply need the 6th element of the list by passing in ‘5’. The reason we pass in 5 and not 6 is because Python uses zero-based indexing where 0 is counted as the 1st position in any list:

print(keywords_list[5])

The output shown below not only has the keywords but also any tags assigned to it. Note that the 6th element of the list is a dictionary which is one of the ways Python stores data. In this case, the dictionary key is ‘keyword’ and the value is a list of dictionaries (one per keyword):

{‘keyword’: <br /> [{‘name’: ‘biometric device’, ‘tags’: {}}, {‘name’: ‘biometric device company’, ‘tags’: {}}, {‘name’: ‘blood pressure monitor wearable device’, ‘tags’: {}}, {‘name’: ‘body monitoring sensors’, ‘tags’: {}}, {‘name’: ‘bodytrak’, ‘tags’: {}}, {‘name’: ‘common workplace injuries’, ‘tags’: {}}, {‘name’: ‘construction workplace injuries’, ‘tags’: {}}, {‘name’: ‘core body temperature’, ‘tags’: {}}, {‘name’: ‘cost of workplace injuries’, ‘tags’: {}}, {‘name’: ‘device performance and health’, ‘tags’: {}}, {‘name’: ‘effects of fatigue in the workplace’, ‘tags’: {}}, {‘name’: ’employee health and performance’, ‘tags’: {}}, {‘name’: ’employees health and safety responsibilities’, ‘tags’: {}}, {‘name’: ‘fatigu accidents’, ‘tags’: {}}, {‘name’: ‘fatigue accidents at work’, ‘tags’: {}}, {‘name’: ‘fatigue accidents in the workplace’, ‘tags’: {}}, {‘name’: ‘fatigue management in the workplace’, ‘tags’: {}}… ]

Rankings 

Luckily you don’t need the keywords to get your rankings. Unlike other rank tracker APIs I’ve worked with (of which their shame shall be spared by remaining nameless!), the Rank Ranger API only requires the:

• 
  Campaign ID
• 
  ****
• 
  Domain
• 
  Search Engine ID

You can even request whether you’d like all the rank data per keyword or the highest rank per keyword using the include_best_rank parameter.
Let’s get the keyword rank data using the above to build the API request using the rank_stats API endpoint.

First, set the parameters:

your_date=”2023-03-21″ <br /> your_domain = ‘slatesafety.com’ <br /> se_id = ‘1’

Build and make the API request, before converting to a list:

r = requests.get(‘https://www.rankranger.com/api/v2/?rank_stats&output=json&key=’ + api_token + ‘&campaign_id=’ + campaigns_id + ‘&domain=’ + your_domain + ‘&****=” + your_date + “&se_id=’ + se_id + ‘&include_best_rank=true’) <br /> rankings_output = pd.read_json(r.text) <br /> rankings_list = rankings_output[‘result’].to_list() <br /> print(rankings_list)

And here is the result of which rank data for the first 4 keywords are shown:

[{‘****’: ’03/21/2023′, ‘url’: ‘slatesafety.com’, ‘lp’: {}, ‘keyword’: ‘physiological monitoring’, ‘tags’: {}, ‘search_volume’: ‘110’, ‘se’: ‘google.com’, ‘se_name’: ‘Google USA’, ‘rank’: ‘-‘}, <br /> {‘****’: ’03/21/2023′, ‘url’: ‘slatesafety.com’, ‘lp’: {}, ‘keyword’: ‘remote physiologic monitoring’, ‘tags’: {}, ‘search_volume’: ‘110’, ‘se’: ‘google.com’, ‘se_name’: ‘Google USA’, ‘rank’: ‘-‘}, <br /> {‘****’: ’03/21/2023′, ‘url’: ‘slatesafety.com’, ‘lp’: {}, ‘keyword’: ‘physiological monitoring solution’, ‘tags’: {}, ‘search_volume’: ‘0’, ‘se’: ‘google.com’, ‘se_name’: ‘Google USA’, ‘rank’: ‘-‘}, <br /> {‘****’: ’03/21/2023′, ‘url’: ‘slatesafety.com’, ‘lp’: {}, ‘keyword’: ‘wearable monitoring solution’, ‘tags’: {}, ‘search_volume’: ‘0’, ‘se’: ‘google.com’, ‘se_name’: ‘Google USA’, ‘rank’: ‘-‘}, … ]

Note that the URL data is actually the domain and that ‘lp’ (presumably landing page) is the ranking URL without the domain portion. You’ll need to combine both the URL and the LP dictionary keys to build the ranking URL which we’ll do in the code later on.

Obviously, the format of the rank data is not very useful to us if we want to export and create a report in Excel or just simply eyeball the data. So we’ll iterate through the dictionary above to create a dataframe. A dataframe is Python’s version of a data table which is akin to what you’d see in a spreadsheet i.e. rows and columns.

First, we’ll create an empty data frame called rankings_df, where all of the data will be stored:

rankings_df = pd.DataFrame(columns=[‘keyword’])

Set an empty list called rows_list which will contain all the rows of data as a list:

rows_list = []

We’ll then work through the rankings_list dictionary (extract printed above) to put the data into a list for an eventual data frame. The URL will be a combination of the URL and landing page. A for loop is a useful coding technique to avoid repeating lines of code, which in this case works by going through each item of rankings_list, indicating to Python which column to store the data, and then adding the result to rows_list:

for i in rankings_list: <br /> temp_dict = {‘****’: i[‘****’], <br /> ‘se_name’: i[‘se_name’], <br /> ‘keyword’: i[‘keyword’], <br /> ‘search_volume’: i[‘search_volume’], <br /> ‘rank’: i[‘rank’], <br /> ‘url’: str(i[‘url’]) + str(i[‘lp’]) <br /> } <br /> rows_list.append(temp_dict)

Once the for loop has finished running (i.e. the code block above), rows_list will be passed into the Pandas DataFrame function to create rankings_df, our rank data table:

rankings_df= pd.DataFrame(rows_list)

The URL slug is wrapped in curly braces which we’ll want to replace:

rankings_df[‘url’] = rankings_df[‘url’].str.replace(‘{‘, ”)

rankings_df[‘url’] = rankings_df[‘url’].str.replace(‘}’, ”)

The rank column also returns ‘-‘ for keywords your site doesn’t rank for. The best response would be to replace this with a ‘100’ and convert the column type to numeric as shown below:

rankings_df[‘rank’] = rankings_df[‘rank’].str.replace(‘-‘, ‘100’)

rankings_df[‘rank’] = rankings_df[‘rank’].astype(float)

To print the data frame:

rankings_df

Now we have a data frame ready to export in CSV format using the Pandas to_csv() function:

rankings_df.to_csv(‘your_filename.csv’)

Taking it further 

If you made it this far (without skimming), congratulations! We covered the basics of using Python to use the RankRanger API which can be used to help you:

• 
  Build custom reporting dashboards
• 
  Extract data at scale for your SEO research

As mentioned, Rank Ranger has insight APIs that can tell you so much about the search intent of a search query which we’ll cover in the next article.