zh
English Español Deutsch Français Italiano Português (Brasil) Русский 中文 日本語
Submit post
Go to Blog
updated

What In The World Is API, and How Do I Use It?

42
Wow-Score
The Wow-Score shows how engaging a blog post is. It is calculated based on the correlation between users’ active reading time, their scrolling speed and the article’s length.

What In The World Is API, and How Do I Use It?

Luke Harsel updated
What In The World Is API, and How Do I Use It?

Table of Contents:

What is an API?
Who are APIs for?
How does an API work?
Turning the raw data into something tangible
What APIs does SEMrush offer?
How can you get it?
Constructing an API Call
API Output
Part 1: Analytics API
Part 2: Projects API
SERP Features Codes
Part 3: Traffic Analytics API
Traffic Analytics Use Cases
Calculating API units usage
Integrating with Google Sheets
Recap
Terms of Use

What is an API?

Application Programming Interface (API) is a method of gathering raw data from SEMrush without using the standard website interface.

If the SEMrush interface is like walking through a grocery store to pick out your groceries by hand; an API is like ordering your groceries in bulk from a same-day drone delivery. 

Pulling data via an API can be automated, so it is an excellent solution for gathering vast sets of data efficiently.

You can get data faster than by using the interface and use it to integrate SEMrush data into your dashboards and other software.

Common uses of APIs include:

  • Custom dashboards for a digital agency’s clients

  • Internal company dashboards for eCommerce, investment firms, etc.

  • Re-selling SEMrush data through a software service

  • Gathering huge sets of data at a faster rate compared to using the SEMrush interface (excellent for extensive keyword research or large Position Tracking campaigns)

  • Pulling Traffic Analytics data on all of your competitors in one report

What’s the catch? Well, if you are unfamiliar with APIs, it can be a bit technical. 

But, if you or a teammate or coworker of yours has experience with an API, the SEMrush API should be relatively easy to pick up. 

This post is for introducing the basics of APIs and how they can be useful. We will get into the specifics of SEMrush APIs as well. For a list of all of our calls, parameters, and technical details, please locate (and bookmark!) the SEMrush API Documentation

Who are APIs for?

An API can be used for an infinite number of purposes. Anyone that can program scripts with API and has the need to gather digital marketing data can make use of it. 

Namely, SEMrush’s API is popular among digital agencies, data scientists, research firms, SaaS software developers, venture capitalists, and re-sellers of SEMrush data. 

How does an API work?

An API operates based on a simple call and response. The elements of an API call (explained further below in this post) create an HTTP address and include parameters (separated by the “&” symbol) for the specific report you are requesting, the database, query, any filters, and of course, your API key. 

Turning the raw data into something tangible

To use an API effectively will require someone familiar with web development to create a script or a similar program that can automate the reception and integration of data.

In computer science, a script is a document written in a dynamic programming language (common languages include Python, Perl, Powershell, Tcl) that send instructions to computer programs to automate tasks.

With a script, you can work with our API calls to turn the .CSV or JSON output into something readable like a spreadsheet or dashboard.

Web developers can write scripts to take raw data from the SEMrush API and integrate it into readable tables, dashboards, reports, and interfaces.

Below I will talk about the different APIs offered on SEMrush and show an example of how a script can pull this data and integrate it into a spreadsheet.

If you are interested in purchasing a script that works with an API from us, you can contact us by phone or email or from the Custom Report page here.

What APIs does SEMrush offer?

SEMrush offers two main API packages:

  1. Standard SEMrush API, which includes:

    1. Analytics API (Domain Analytics and Keyword Research)

    2. Projects API (Site Audit and Position Tracking) 

    3. Accounts API (how many API units remain on your account, query history, etc.) 

  2. Traffic Analytics API (a separate API for Traffic Analytics data, introduced in 2019)

How can you get it?

To use our Analytics API, Projects API, and Accounts API, you need to:

  • Subscribe to the Business SEMrush plan

  • Purchase the API package and the number of API units that will fit your needs 

To use SEMrush Traffic Analytics API, you do not need a SEMrush subscription; you can purchase it separately. The Traffic Analytics API comes in two forms: Basic and Extended. 

  • The Traffic Analytics Basic API lets you gather data from the Traffic Analytics Overview report. 

  • Traffic Analytics Extended API gathers data from the more in-depth reports in this tool: Traffic Sources, Geographic Distribution, Destination Sites, and Subdomains.

The Traffic Analytics API can be easily tested online. Go to Traffic Analytics API Demo Constructor and investigate what data you can get in each of the packages, export it, see how the query works, etc. 

For more details, please feel free to refer to Traffic Analytics API documentation.

To add an API to your plan, reach out to our sales team. We will help you decide how many API units you need and provide you with your API key. 

Your API key can be found in the API units tab of the Subscription Info page

semrush-api-key

Constructing an API Call

To receive data via Analytics API, you need to build an API call (also known as a request). 

An API call is a request sent to the server for data from the SEMrush database.

The API call is constructed by combining parameters to define the data that you want to receive. Parameters include the type of report, your API key, the domain you are querying, the database, display date, export columns, filters, and more. 

Below is a color-coded breakdown of a Domain Overview API call for seobook.com (US database) with 8 columns. 

sample-api-call-semrush

The parameters in this call are as follows:

semrush-api-parameters

Notice the display date is set to January 2018, making this a call for historical data (20180115 represents January 15th, 2018 in YYYYMM15 format). Since this call is in our Analytics database, the data will represent a monthly figure. Therefore, 15 is the standard number to use. 

Using Projects API, if you are pulling data from a Position Tracking project, you can specify a single date to pull the data for. 

The parameters and number of lines included in each call will determine the cost of the call in API units. A call that asks for six columns of data for one hundred domains will cost ten times the amount of units compared to a call asking for the same six columns of data for ten domains. 

Examples of all parameters, columns, filters, sorting, and databases can all be found in the API Documentation.

Column names, for example, can be found in the “Columns” section of the API Documentation.

What In The World Is API, and How Do I Use It?. Image 3

In addition to the basic parameters, there are also parameters for adding filters, sorting by metrics, and setting a display limit to the number of lines the call will return. All of these parameters can be found in the menu on the API documentation.

API Output

After building your API call (or request) and sending it to our server, SEMrush will return raw data with the column headers and the data. If you type the call into a browser’s address bar, for example, it will return the raw data in the browser and look like this: 

sample-api-response

This response is 1 line because it is only reporting data for 1 domain. 

This output is technically a .CSV file. The outputs of our APIs are:

  • Analytics API: .CSV

  • Traffic Analytics API: .CSV

  • Projects API: JSON

  • Accounts API: .CSV

Part 1: Analytics API

Now, what can be done with the Analytics API? This API can be used to pull reports on domain analytics, competitive research, keyword research, backlinks, advertising research, and more.

These are the classic reports on SEMrush used to study the search positions and online visibility of your competitors or industry. If competitive research is a part of your workflow, using API will accelerate the process.

For gathering total website traffic estimations (not just traffic from search),you would want to look into the Traffic Analytics API. Traffic Analytics offers a breakdown of traffic from search, social, direct, paid, and referral, in addition to monthly visits, time on page, bounce rate, pages/session, and more. 

Using a Script with Analytics API

Now, if you had a script that could process API calls into a formatted table, you could make queries in bulk and get super-fast results. For example, if you had a list of ten domains like this:

What In The World Is API, and How Do I Use It?. Image 5

You could use a script to analyze everything listed in the spreadsheet. Pictured below is a section of a script written to pull data through the SEMrush API and import the lines to a clean spreadsheet on the computer’s desktop.

What In The World Is API, and How Do I Use It?. Image 6

Notice at the end of the GIF the time it took to make this call was roughly 1.3 seconds. Now, the file can be found on the desktop. 

What In The World Is API, and How Do I Use It?. Image 7

Those are the basics of API. Of course, our example only showed the process with 10 domains, and it took one second. You can use a similar process to pull data on hundreds of thousands of domains in only minutes. 

To familiarize yourselves with our API language and how to format a call, developers need to read our API documentation

Part 2: Projects API 

The Projects API allows users to create, edit, and manage projects using the Site Audit and Position Tracking tools. 

You can pull reports from existing projects or create a new project and configure it with an API call. Because the interface makes it easy to configure a Project with specific settings, people will commonly create their Projects in the interface and then use API to pull the data. 

Please note: Projects API shares API units with Analytics API. Traffic Analytics API, however, is separate from Analytics and Projects and does not use API units. 

Position Tracking can track you and your competitors’ keyword rankings and discover local competitors. Our Site Audit tool will crawl a website and provide you with a detailed list of issues on the site that you can fix to improve its SEO. 

These two tools are especially great for client reporting. They can show overview metrics like the general health score of a website (Site Audit) and visibility across target keywords (Position Tracking). For this reason, the Projects API is a great solution for automating client-facing or internal dashboards. 

Another great reason to use Projects API is for the speed. Compared to the interface, the API will be able to export data from large Projects at a more efficient rate. 

Below is an example of how it would look using a script to pull data from an existing Project into a simple spreadsheet. 

Using a Script for Projects API

First, here is the Position Tracking Project on SEMrush. The domain is ebay.com, and it is tracking 81 keywords and 20 competitors.

What In The World Is API, and How Do I Use It?. Image 8

Here is a script that is formatted to GET the data from the existing Position Tracking Project.

What In The World Is API, and How Do I Use It?. Image 9

Note how the script only took six seconds (Time --- 0:00:06.3727)to export thousands of rows of information. Below is the spreadsheet that the script created — all of the keywords in the campaign along with the competitor’s ranking pages.

What In The World Is API, and How Do I Use It?. Image 10

SERP Features Codes

If you are pulling data from a Position Tracking campaign, you will see a column for the SERP Features that the tracked domain ranks for. The SERP Features codes as they appear in API are as follows:

  • fsn: Featured snippet

  • geo: Local pack

  • rev: Reviews

  • stl: Site links

  • vid: Video

  • vib: Featured video

  • new: Top stories

  • rel: People also ask

  • img: Images

  • twt: Twitter

  • knw: Instant answer

  • kng: Knowledge panel

  • shp: Shopping ads

  • adt: AdWords top

  • adb: AdWords bottom

Technical Details - Projects API

Unlike the Analytics API, all Project API requests operate through the following HTTP commands:

POST: Send a POST call to create something new, e.g., create a new project, enable Position Tracking/Site Audit tool. 

PUT: Send a PUT call when you want to make some changes to your existing projects, e.g., change the keywords or competitors in Position Tracking, change the crawled page limit. 

GET: Send a GET call to pull some reports of current projects, e.g., daily organic position report, issues of a site audit campaign. 

DELETE: Send a DELETE call to delete anything existing, e.g., delete an existing project, delete keywords from an existing project.

Part 3: Traffic Analytics API 

The other API that is separate from any SEMrush subscription is Traffic Analytics. Traffic Analytics allows you to gather traffic estimations for a website. With the speed of API, you can research this data more efficiently. 

Traffic Analytics API does not come as a part of the main SEMrush API. It has to be purchased separately from any SEMrush subscription, or in addition to any subscription. 

Please note that we offer two versions of this API:

  1. Basic API: Traffic Overview report

  2. Extended API: Traffic Overview report, Traffic Sources, Traffic Destinations, Geographic Distribution, and Subdomains

This API can integrate seamlessly with software like Google Sheets, Excel, Salesforce, Tableau, Power BI, and more. 

Traffic Analytics Use Cases

Some examples of how you could use this API include:

  • Qualifying new leads

  • Evaluating new markets 

  • Enhancing an existing SaaS offering with traffic data

  • Providing data on prospects to your sales team

  • Evaluating new business partners and prospects 

To qualify new leads, you could take your list of domains and pull all of their Traffic Overview data to see which leads have the highest website engagement and which websites show weak engagement from their visitors. The leads with the worst engagement could be the best places to start if you are pitching website services. 

To evaluate a new market, you could gather a list of domains in the market you want to learn about, and then make an API call to pull their traffic data. An Overview call would allow you to see the average qualities of the market, such as website visits, mobile vs. desktop traffic, time on page, pages per session, and more. 

If you already offer a SaaS platform for people to study websites or businesses, adding SEMrush Traffic Analytics data to your offering would give powerful insights into this business’s online presence — perfect data for competitive analysis. 

The Traffic Analytics API could also integrate with a sales prospecting software to give your sales team extra info about each opportunity. Which means they can always bring data to their sales pitch. 

If you need to evaluate new business partners and prospects, this API could integrate with your existing information and provide insight into their strengths and weaknesses online. 

Using Traffic Analytics API with a Script

Again, this API can easily integrate into a script. Let’s take the following ten domains from a spreadsheet: 

What In The World Is API, and How Do I Use It?. Image 11

Use a script to pull the data: 

What In The World Is API, and How Do I Use It?. Image 12

And the resulting info on these domains populates into this spreadsheet: 

What In The World Is API, and How Do I Use It?. Image 13

Go beyond competition

Get started with SEMrush Traffic Analytics API

Please specify a valid domain, e.g., www.example.com

Calculating API Units Usage

As you plan your Analytics and Projects API calls, you will need to estimate how many API units you will be spending. 

Keep in mind: Traffic Analytics API does not use API units, and therefore you won’t need to calculate units, and Accounts API calls are free. Calculating API Units is only relevant for Analytics and Projects API calls. 

Each Analytics and Projects call has its own price, and for historical data, the price will go up. The API documentation will tell you the price in units per line of each call. 

What In The World Is API, and How Do I Use It?. Image 14

To estimate your budget, you will need to estimate a few things:

  • If the API is being used internally or externally

  • What kind of data is being used (which reports you will use & if you want live or historical data)

  • How much data you will need (how many calls you will be making every month)

To calculate the cost of a call, you would need to multiply the cost per line by the number of lines in the call. 

What is a line?

Well, if you think of the response as a .csv file, each row of data in the response is a line. Each line could represent metrics for a particular keyword, domain, or URL depending on your report. Note in the image below how the call has a display_limit parameter of 25 and therefore returns 25 lines. 

What In The World Is API, and How Do I Use It?. Image 15

Another example would be if you want to pull the top 100 keywords for a domain using live data; you would use the “domain_organic” call, which costs 10 API units per line (live data). 

What In The World Is API, and How Do I Use It?. Image 16

Since you want 100 keywords, that would be 100 lines of data. So, to calculate the cost of this in API units, we would multiply 10 (units per line) * 100 (lines in your call) = 1000 API units. 

Of course, calculating API units usage will be more complicated than that as you use API more extensively, but the basic logic remains the same. You will be charged API units for every line of data that you request. 

Integrating with Google Sheets

Using API with Google Sheets is one of the simplest ways to integrate API with another platform. 

Much like Microsoft Excel, Google Spreadsheets supports a wide array of functions.

By using functions like IMPORTDATA, TRANSPOSE, and SPLIT, you can enter your API calls into a cell and populate the spreadsheet with formatted data.

For example, a Domain Overview report request example using IMPORTDATA would look similar to the following:

(importdata("https://api.semrushchina.cn/type=domain_rank&key=abcdefghijklm0pqrstuv123&export_columns=Dn,Rk,Or,Ot,Oc,Ad,At,Ac&domain=seobook.com&database=us")

The results of the call will populate into the cell that you entered the formula.

What In The World Is API, and How Do I Use It?. Image 17

We have an article in our Knowledge Base that shows you how to use Traffic Analytics API in Google Sheets. Check it out here

Recap

If you want to gather more data at a faster pace than the interface, SEMrush API is your perfect solution.

Adding the standard API to your subscription is available after subscribing to the Business level and will grant you access to our Analytics API, Projects API, and Accounts API. These APIs will let you pull research data on your competitor’s search performance, keyword research, and build awesome progress dashboards. 

Request API access here

Anyone can purchase SEMrush Traffic Analytics API - with or without a SEMrush subscription. This API is amazing for evaluating markets and potential business partners and investments.

Go beyond competition

Get started with SEMrush Traffic Analytics API

Please specify a valid domain, e.g., www.example.com

Terms of Use

Before using our API, you need to read and agree to our terms of use. If you wish to resell our data via API, a separate agreement must be made. Full terms of use can be found here.

Luke Harsel
SEMrush

SEMrush employee.

I write articles on the SEMrush Knowledge Base and blog to show people how the tools on SEMrush can make it easier to participate in digital marketing. When I'm not at work I like to write music and spend time in nature.
Share this post
or

Comments

2000
Expert

Provides valuable insights and adds depth to the conversation.

Thanks for the great info! Data is necessary to developing and maintaining an effective strategy, but only if you know what to do with that data. Thanks for making our lives so much easier!
Newcomer

Either just recently joined or is too shy to say something.

Is there a way to edit this API so it pulls a specific URL rather than the domain overview?
Luis Revuelto
Enthusiast

Occasionally takes part in conversations.

Thank you for your detailed explanation. I was trying a similar call for a google analytics report. The API Documentation is good, but you made it easier :)
Newcomer

Either just recently joined or is too shy to say something.

Thank you :)
Newcomer

Either just recently joined or is too shy to say something.

Why is your API price in terms of dollars is nowhere to be found?
Is it because your API offering is not production ready yet?
SEMrush

SEMrush employee.

Ray Smith
Hello Ray!
API pricing can be seen on the API documentation page, one US dollar is equal to approximately 20,000 API units. In order to estimate a budget and get the proper amount to fit your needs you can contact our Sales department or buy units directly from the user profile page.
Mike Isaac
Superstar

Knows everything… well, almost.

Hey SeoKungFu! If you are referring to the API call example listed in this article, this is actually coming straight from the API Documentation example. Our API is used by thousands of users and has been tested multiple times without an issue. Does this answer your question? If not, do you mind specifying a little further so I can give you a better response? Thanks!
SeoKungFu
Expert

Provides valuable insights and adds depth to the conversation.

BTW, I am curious whether you have stress-tested yours, for this matters both in terms of security and performance ?
SeoKungFu
Expert

Provides valuable insights and adds depth to the conversation.

SeoKungFu
I haven't ( yet :D )

Send feedback

Your feedback must contain at least 3 words (10 characters).

We will only use this email to respond to you on your feedback. Privacy Policy

Thank you for your feedback!