As a former Customer Support Specialist at SEMrush, one common question I would receive from customers was, “What is API?” Now, trust me; I understand this can be difficult to understand. It took me quite a while to really get what API is and how to use it.
Since so many people ask this question, I created this post to help you understand API.
SEMrush and API: A Love Story
Let's start with the obvious — What is API?
Application Programming Interface (API) is a feature of SEMrush that allows you to receive the raw data offered in SEMrush without having to manually log into the software. By making an API call, you will be able to receive information right in your browser without having to navigate SEMrush itself.
Our customers typically use this feature if they just want to see the data we offer and not use any of our interface features. Or, if they have their own custom software and they would like to implement our data into it.
[Ed. Note] If you are looking to integrate our data with your own, you will need to make sure it falls within our API guidelines. You can review our guidelines here. If you are unsure if you are in compliance with our terms, feel free to contact us and we will be happy to assist you.
How to Use SEMrush API
PLEASE NOTE: To use our API, you must upgrade your account. We no longer offer subscriptions with API units included. If you are interested in learning more about our API options, please contact us.
The SEMrush API Documentation page will be your best friend when you work with API, as every call will be broken down and explained for you here. The proper formatting will be displayed as well, so you can correctly structure your API calls. These calls can be made by pasting an API call into a web browser. This will then spit back the information for you.
Take a look at the Domain Organic Search Keywords API Call. Once you select the API call and click the arrow, you will see this API call broken down for you. When looking at these different categories listed, refer to the Request example listed at the bottom of the box. This will show you what each part of the URL means and how you receive the result shown in the Response example.
If you were to enter the URL seen in the Request example, you would receive the result shown in the Response example. For each category listed in this box, it will explain how to use or understand that specific part of the API call. If you see a blue link for one of the categories, you can click the link and you will be redirected to the part of the page that explains that specific category.
Once you're logged into your SEMrush account, the listed API calls will have your API key inserted into each Request example. You can then simply copy and paste these examples into your browser and see the information displayed in the example.
API Units: What You Need to Know
SEMrush’s API interface works with API units. Each API call has a particular price per line of data. Depending on how many lines you request in your API call, it will cost you a certain amount of units. For example, if you make an API call for 10 lines of data — and each line costs 10 API units — it would cost you 100 API units to make that API call.
The price of each API call is listed on the API Documentation page. You can apply these to all of the API calls you see on our API Documentation page.
What Does an API Call Look Like?
For this example, we'll use the Domain Overview (All Databases) API call. Since we are specifying the US database in the call below, we will only see results for the US Database. This is the request example we list on the API page that you can reference.
Below, we see the API call for a Domain Overview Report for seobook.com [Ed. Note: Emphasized in green and bold for clarity]:
Now we can further break this call down piece by piece to further understand what information we are receiving. Each section is broken up with the “&” symbol:
http://api.semrush.com/?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX (API Key)
&type=domain_ranks (Type of Report; Domain Overview)
&export_columns=Db,Dn,Rk,Or,Ot,Oc,Ad,At,Ac (Information We Will Receive; Database, Domain, Rank, Organic Keywords, Organic Traffic, Organic Cost, Adwords Keywords, Adwords Traffic, Adwords Cost)
&domain=seobook.com (domain being queried)
&database=us (what database we are seeing data for)
When you enter this API call into your browser, you will see the following information as a result:
Database;Domain;Rank;Organic Keywords;Organic Traffic;Organic Cost;Adwords Keywords;Adwords Traffic;Adwords Cost us;seobook.com;25689;3040;38517;254377;0;0;0
You can apply this same concept to all of the calls you see within the Analytics API page. When you break it down as shown above, it does not seem as complex.
To better understand them, I usually break down and edit API calls in a txt window. This method is great if you are receiving an error in your API call and are not sure why. By breaking it down and comparing it to the request examples listed on our API Documentation page, you can see what you may have done wrong.
SEMrush Projects API
Our Projects API refers to API calls for the Site Audit tool and the Position Tracking tool. The Projects API allows you to create, edit and manage any projects you use within Position Tracking and Site Audit. You can create and delete projects, along with add keywords and receive reports on your current projects.
As mentioned earlier, to use our API, you must upgrade your account. We no longer offer subscriptions with API units included. If you are interested in learning more about our API options, please contact us.