So, you’re interested in using the SEMrush Project API, but not sure where to start? You’ve come to the right place!
Project API allows you to gather raw data from the Site Audit and Position Tracking tools on SEMrush to use any way you please. You can use this API to analyze big data and enhance your own software with easy integration.
We’ve published a blog post about the SEMrush API for Domain and Keyword Analytics before, and we have an API Documentation page with detailed instructions. This post is intended to specifically walk you through how to use the Projects API.
Why Use the Project API?
By using Projects API, you can track you and your competitors’ keyword rankings, discover local competitors, fix websites’ on-page issues from a single location, and more.
The Projects API allows users to create, edit and manage projects that use the Site Audit and Position Tracking tools. API is just another way for users to interact with SEMrush. You can get reports from existing projects, or create a new project with the API and view it on the website.
To ensure you can set up your own project by API, we’ll walk through the process from creating a new project to running a campaign and pulling reports.
How to Use the Project API
In order to use the SEMrush 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. Once you find your API Key, you will want to keep this private from other unauthorized users of your account. This key is unique to you, making sure you are charged the necessary API units for any calls you make using your key.
This API key can be found by in your API account settings page. You can also see how many API units you have left on this page.
Request Format
Unlike the Analytics API, all Project API requests use HTTP methods such as POST, PUT, GET or DELETE. You can’t simply type in the calls in your web browser except for GET request. Although there are many API calls in Project API page, they all fall into these four types of requests:
POST: You send a POST call to create something new, e.g. create a new project, enable Position Tracking/Site Audit tool.
PUT: 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: You can send a GET call to pull some reports of current projects, e.g. daily organic position report, get issues of a site audit campaign
DELETE: You can send a DELETE call to delete anything existing, e.g. delete an existing project, delete keywords from an existing project.
Create a NEW project
Whether you want to set up a Position Tracking or Site Audit project, the first thing you’ll have to do is create a new project. This means naming the project, choosing a domain, adding keywords and competitors to track, and grouping keywords with tags.
The last three parameters are advanced steps for setting up Position Tracking and are not required in this step. If you just want to set up a Site audit Project, you can just leave those parts blank. If you want to set up a Position Tracking project in the future, don’t worry. You can also add keywords and competitors in the future.
The request URL (POST) is as follow:
https://api.semrush.com/management/v1/projects?key={API_key}
Enable Position Tracking/Site Audit Tool
Once you have set up the project, then you will need to enable the Position Tracking or Site Audit function of that project.
For Position Tracking, the enable request unlocks the possibility to receive daily updates on a project domain and its competitors’ keyword rankings. You need to post the tracking URL, location information, email notification in the request.
For Site Audit, it allows you to schedule audits, include or exclude pages from the crawl and set the number of pages to crawl. You will need to post the domain, scheduled crawl date, page limit, and pages to allow/disallow in the request.
The request URL (POST) is as follow:
https://api.semrush.com/management/v1/projects/{ID}/tracking/enable?key={API_key}
https://api.semrush.com/management/v1/projects/{ID}/siteaudit/enable?key={API_key}
Run Audit
When we finish enabling the tools, we are able to get the report of the Position Tracking tool. However, there is one more step for the Site Audit tool: running the audit. Just send the POST request, no detail needed. It will respond with a snapshot id, which we can get a report of this audit with.
{"snapshot_id":"54102d92e4b0f889a040c9c8"}
The request URL (POST) is as follow:
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/launch?key={API_key}
Receive Your Report
Now you can enjoy the beautiful data from your project. You can receive the organic report, AdWords report, and competitors discovery report of your Position Tracking project. From your Site Audit project, you can get the issues report for a single crawl or your all time issues report of a campaign for your Site Audit project.
Since these API calls are all GET request, you can simply enter the request URLs in your browser and you will see the well-organized JSON format response as follow.
The request URL (GET) is as follow:
https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/info?key={API_key}
Samples
The following sample code is run under the Python 2 environment. These four calls cover the process of setting up a new project to pulling the results of a Site Audit. You can copy & paste the sample code in your script program to test. Don’t forget to enter your own API_Key in the script.
Set up a new project
import requests
url = "https://api.semrush.com/management/v1/projects"
querystring = {"key":"{API_Key}"}
payload = "{ \"project_name\":\"ProjectAPI\",\"url\":\"amazon.com\",\"competitors\":[\"google.com\", \"ebay.com\"],\"keywords\":[{\"keyword\":\"search tool\",\"tags\":[\"search\"]}, {\"keyword\":\"search engine\",\"tags\":[\"search\"]}]}"
headers = {
'content-type': "application/json",
'cache-control': "no-cache"
}
response = requests.request("POST", url, data=payload, headers=headers, params=querystring)
print(response.text)Enable site audit
url = "https://api.semrush.com/management/v1/projects/{ID}/siteaudit/enable"
querystring = {"key":"{API_Key}"}
payload = "{\r\n\t\"domain\": \"amazon.com\",\r\n\t\"scheduleDay\":0,\"notify\":false,\"pageLimit\":1000,\"userAgentType\":1,\"device\":desktop\r\n\t}\r\n\t\r\n"
headers = {
'content-type': "application/json",
'cache-control': "no-cache"
}
response = requests.request("POST", url, data=payload, headers=headers, params=querystring)
print(response.text)Run Audit
url = "https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/launch"
querystring = {"key":"{API_Key}"}
headers = {
'cache-control': "no-cache"
}
response = requests.request("POST", url, headers=headers, params=querystring)
print(response.text)Get report
url = "https://api.semrush.com/reports/v1/projects/{ID}/siteaudit/info"
querystring = {"key":"{API_Key}"}
headers = {
'cache-control': "no-cache"
}
response = requests.request("GET", url, headers=headers, params=querystring)
print(response.text)Conclusion
API is an efficient way to generate information quickly and get the data you're seeking. In order 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.