What in the World Is API, and How Do I Use It?

What is an API?

Application Programming Interface (API) is simply a method of gathering earthy information from Semrush without utilizing the modular website interface.

If the Semrush interface is similar walking done a market store to prime retired your groceries by hand; an API is similar ordering your groceries successful bulk from a same-day drone delivery. 

Pulling information via an API tin beryllium automated, truthful it is an fantabulous solution for gathering immense sets of information efficiently.

You tin get information faster than by utilizing the interface and usage it to integrate Semrush information into your dashboards and different software.

Common uses of APIs include:

• Custom dashboards for a integer agency’s clients

• Internal institution dashboards for eCommerce, concern firms, etc.

• Re-selling Semrush information done a bundle service

• Gathering immense sets of information astatine a faster complaint compared to utilizing the Semrush interface (excellent for extended keyword probe oregon ample Position Tracking campaigns)

• Pulling Traffic Analytics information connected each of your competitors successful 1 report

What’s the catch? Well, if you are unfamiliar with APIs, it tin beryllium a spot technical. 

But, if you oregon a teammate oregon coworker of yours has acquisition with an API, the Semrush API should beryllium comparatively casual to prime up. 

This station is for introducing the basics of APIs and however they tin beryllium useful. We volition get into the specifics of Semrush APIs arsenic well. For a database of each of our calls, parameters, and method details, delight find (and bookmark!) the Semrush API Documentation.

Who are APIs for?

An API tin beryllium utilized for an infinite fig of purposes. Anyone that tin programme scripts with API and has the request to stitchery integer selling information tin marque usage of it. 

Namely, Semrush’s API is fashionable among integer agencies, information scientists, probe firms, SaaS bundle developers, task capitalists, and re-sellers of Semrush data. 

How does an API work?

An API operates based connected a elemental telephone and response. The elements of an API telephone (explained further beneath successful this post) make an HTTP code and see parameters (separated by the “&” symbol) for the circumstantial study you are requesting, the database, query, immoderate filters, and of course, your API key. 

Turning the earthy information into thing tangible

To usage an API efficaciously volition necessitate idiosyncratic acquainted with web improvement to make a publication oregon a akin programme that tin automate the reception and integration of data.

In machine science, a publication is simply a papers written successful a dynamic programming connection (common languages see Python, Perl, Powershell, Tcl) that nonstop instructions to machine programs to automate tasks.

With a script, you tin enactment with our API calls to crook the .CSV oregon JSON output into thing readable similar a spreadsheet oregon dashboard.

Web developers tin constitute scripts to instrumentality earthy information from the Semrush API and integrate it into readable tables, dashboards, reports, and interfaces.

Below I volition speech astir the antithetic APIs offered connected Semrush and amusement an illustration of however a publication tin propulsion this information and integrate it into a spreadsheet.

If you are funny successful purchasing a publication that works with an API from us, you tin interaction america by telephone oregon email oregon from the Custom Report leafage here.

What APIs does Semrush offer?

Semrush offers 2 main API packages:

1. Standard Semrush API, which includes:
   1. Analytics API (Domain Analytics and Keyword Research)
   2. Projects API (Site Audit, Position Tracking, and Project Management) 
2. Traffic Analytics API (a abstracted API for Traffic Analytics data, introduced successful 2019)

How tin you get it?

To usage our Analytics API and Projects API, you request to:

• Subscribe to the Business Semrush plan

• Purchase the API bundle and the fig of API units that volition acceptable your needs 

To usage Semrush Traffic Analytics API, you archetypal request to person a Semrush subscription program (it doesn’t person to beryllium a Business plan). The Traffic Analytics API comes successful 2 forms: Basic and Extended. 

• The Traffic Analytics Basic API lets you stitchery information from the Traffic Analytics Overview report. 

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

For much details, delight consciousness escaped to notation to Traffic Analytics API documentation.

You tin adhd a Traffic Analytics API to your program straight from your Subscription Info page oregon you tin scope retired to our income team. We volition assistance you determine however galore API units you request and supply you with your API key. 

Your API cardinal tin beryllium recovered successful the API units tab of the Subscription Info page. 

Constructing an API Call

To person information via Analytics API, you request to physique an API telephone (also known arsenic a request). 

An API telephone is simply a petition sent to the server for information from the Semrush database.

The API telephone is constructed by combining parameters to specify the information that you privation to receive. Parameters see the benignant of report, your API key, the domain you are querying, the database, show date, export columns, filters, and more. 

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

The parameters successful this telephone are arsenic follows:

Notice the show day is acceptable to January 2018, making this a telephone for humanities information (20180115 represents January 2018 successful YYYYMM15 format). Since this telephone is successful our Analytics database, the information volition correspond a monthly figure. Therefore, 15 is conscionable a placeholder to usage for the time successful the modular YYYYMMDD format.

Using Projects API, if you are pulling information from a Position Tracking project, you tin specify a azygous day to propulsion the information for. 

The parameters and fig of lines included successful each telephone volition find the outgo of the telephone successful API units. A telephone that asks for six columns of information for 1 100 domains volition outgo 10 times the magnitude of units compared to a telephone asking for the aforesaid six columns of information for 10 domains. 

Examples of each parameters, columns, filters, sorting, and databases tin each beryllium recovered successful the API Documentation.

Column names, for example, tin beryllium recovered successful the “Columns” conception of the API Documentation.

In summation to the basal parameters, determination are besides parameters for adding filters, sorting by metrics, and mounting a show bounds to the fig of lines the telephone volition return. All of these parameters tin beryllium recovered successful the paper connected the API documentation.

API Output

After gathering your API telephone (or request) and sending it to our server, Semrush volition instrumentality earthy information with the file headers and the data. If you benignant the telephone into a browser’s code bar, for example, it volition instrumentality the earthy information successful the browser and look similar this: 

This effect is 1 enactment due to the fact that it is lone reporting information 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 tin beryllium done with the Analytics API? This API tin beryllium utilized to propulsion reports connected domain analytics, competitory research, keyword research, backlinks, advertizing research, and more.

These are the classical reports connected Semrush utilized to survey the hunt positions and online visibility of your competitors oregon industry. If competitory probe is simply a portion of your workflow, utilizing API volition accelerate the process.

For gathering full website postulation estimations (not conscionable postulation from search), you would privation to look into the Traffic Analytics API. Traffic Analytics offers a breakdown of postulation from search, social, direct, paid, and referral, successful summation to full monthly visits, clip connected page, bounce rate, pages/session, and more.

Using a Script with Analytics API

Now, if you had a publication that could process API calls into a formatted table, you could marque queries successful bulk and get super-fast results. For example, if you had a database of 10 domains similar this:

You could usage a publication to analyse everything listed successful the spreadsheet. Pictured beneath is simply a conception of a publication written to propulsion information done the Semrush API and import the lines to a cleanable spreadsheet connected the computer’s desktop.

Notice astatine the extremity of the GIF the clip it took to marque this telephone was astir 1.3 seconds. Now, the record tin beryllium recovered connected the desktop. 

Those are the basics of API. Of course, our illustration lone showed the process with 10 domains, and it took 1 second. You tin usage a akin process to propulsion information connected hundreds of thousands of domains successful lone minutes. 

To familiarize yourselves with our API connection and however to format a call, developers request to work our API documentation. 

Part 2: Projects API 

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

You tin propulsion reports from existing projects oregon make a caller task and configure it with an API call. Because the interface makes it casual to configure a Project with circumstantial settings, radical volition commonly make their Projects successful the interface and past usage API to propulsion the data. 

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

Position Tracking tin way you and your competitors’ keyword rankings and observe section competitors. Our Site Audit instrumentality volition crawl a website and supply you with a elaborate database of issues connected the tract that you tin hole to amended its SEO. 

These 2 tools are particularly large for lawsuit reporting. They tin amusement overview metrics similar the wide wellness people of a website (Site Audit) and visibility crossed people keywords (Position Tracking). For this reason, the Projects API is simply a large solution for automating client-facing oregon interior dashboards. 

Another large crushed to usage Projects API is for the speed. Compared to the interface, the API volition beryllium capable to export information from ample Projects astatine a much businesslike rate. 

Below is an illustration of however it would look utilizing a publication to propulsion information from an existing Project into a elemental spreadsheet. 

Using a Script for Projects API

First, let’s accidental we person a Position Tracking run connected Semrush. The domain is ebay.com, and it is tracking 81 keywords and 20 competitors. The Project ID (found successful the URL) is 1565219.

Here is simply a publication that is formatted to GET the information from the existing Position Tracking Project.

Note however the publication lone took six seconds (Time --- 0:00:06.3727)to export thousands of rows of information. Below is the spreadsheet that the publication created — each of the keywords successful the run on with the competitor’s ranking pages.

SERP Features Codes

If you are pulling information from a Position Tracking campaign, you volition spot a file for the SERP Features that the tracked domain ranks for. The SERP Features codes arsenic they look successful API are arsenic follows:

• fsn: Featured snippet

• geo: Local pack

• rev: Reviews

• stl: Site links

• vid: Video

• vib: Featured video

• new: Top stories

• rel: People besides 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, each Project API requests run done the pursuing HTTP commands:

POST: Send a POST telephone to make thing new, e.g., make a caller project, alteration Position Tracking/Site Audit tool. 

PUT: Send a PUT telephone erstwhile you privation to marque immoderate changes to your existing projects, e.g., alteration the keywords oregon competitors successful Position Tracking, alteration the crawled leafage limit. 

GET: Send a GET telephone to propulsion immoderate reports of existent projects, e.g., regular integrated presumption report, issues of a tract audit campaign. 

DELETE: Send a DELETE telephone to delete thing existing, e.g., delete an existing project, delete keywords from an existing project.

Part 3: Traffic Analytics API 

The different API that is abstracted from immoderate Semrush subscription is Traffic Analytics. Traffic Analytics allows you to stitchery postulation estimations for a website. With the velocity of API, you tin probe this information much efficiently. 

Traffic Analytics API does not travel arsenic a portion of the main Semrush API. It has to beryllium purchased separately from immoderate Semrush subscription, oregon successful summation to immoderate subscription. 

Please enactment that we connection 2 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 tin integrate seamlessly with bundle similar Google Sheets, Excel, Salesforce, Tableau, Power BI, and more. 

Traffic Analytics Use Cases

Some examples of however you could usage this API include:

• Qualifying caller leads

• Evaluating caller markets 

• Enhancing an existing SaaS offering with postulation data

• Providing information connected prospects to your income team

• Evaluating caller concern partners and prospects 

To qualify caller leads, you could instrumentality your database of domains and propulsion each of their Traffic Overview information to spot which leads person the highest website engagement and which websites amusement anemic engagement from their visitors. The leads with the worst engagement could beryllium the champion places to commencement if you are pitching website services. 

To evaluate a caller market, you could stitchery a database of domains successful the marketplace you privation to larn about, and past marque an API telephone to propulsion their postulation data. An Overview telephone would let you to spot the mean qualities of the market, specified arsenic website visits, mobile vs. desktop traffic, clip connected page, pages per session, and more. 

If you already connection a SaaS platform for radical to survey websites oregon businesses, adding Semrush Traffic Analytics information to your offering would springiness almighty insights into this business’s online beingness — cleanable information for competitory analysis. 

The Traffic Analytics API could besides integrate with a income prospecting software to springiness your income squad other info astir each opportunity. Which means they tin ever bring information to their income pitch. 

If you request to evaluate caller concern partners and prospects, this API could integrate with your existing accusation and supply penetration into their strengths and weaknesses online. 

Using Traffic Analytics API with a Script

Again, this API tin easy integrate into a script. Let’s instrumentality the pursuing 10 domains from a spreadsheet: 

Use a publication to propulsion the data: 

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

Calculating API Units Usage

As you program your Analytics and Projects API calls, you volition request to estimation however galore API units you volition beryllium spending. 

Keep successful mind: Traffic Analytics API does not usage API units, and truthful you won’t request to cipher units, and Accounts API calls are free. Calculating API Units is lone applicable for Analytics and Projects API calls. 

Each Analytics and Projects telephone has its ain price, and for humanities data, the terms volition spell up. The API documentation volition archer you the terms successful units per line of each call. 

To estimation your budget, you volition request to estimation a fewer things:

• If the API is being utilized internally oregon externally

• What benignant of information is being utilized (which reports you volition usage & if you privation unrecorded oregon humanities data)

• How overmuch information you volition request (how galore calls you volition beryllium making each month)

To cipher the outgo of a call, you would request to multiply the outgo per enactment by the fig of lines successful the call. 

What is simply a line?

Well, if you deliberation of the effect arsenic a .csv file, each enactment of information successful the effect is simply a line. Each enactment could correspond metrics for a peculiar keyword, domain, oregon URL depending connected your report. Note successful the representation beneath however the telephone has a display_limit parameter of 25 and truthful returns 25 lines. 

Another illustration would beryllium if you privation to propulsion the apical 100 keywords for a domain utilizing unrecorded data; you would usage the “domain_organic” call, which costs 10 API units per enactment for unrecorded data, oregon 50 API units per enactment for humanities data. 

Of course, calculating API units usage volition beryllium much analyzable than that arsenic you usage API much extensively, but the basal logic remains the same. You volition beryllium charged API units for each enactment of information that you request. 

To presumption your API units balance, spell to your Semrush Profile - Subscription info - API units.

Integrating with Google Sheets

Using API with Google Sheets is 1 of the simplest ways to integrate API with different platform. 

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

By utilizing functions similar IMPORTDATA, TRANSPOSE, and SPLIT, you tin participate your API calls into a compartment and populate the spreadsheet with formatted data.

For example, a Domain Overview study petition illustration utilizing IMPORTDATA would look akin to the following:

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

The results of the telephone volition populate into the compartment that you entered the formula.

We person an nonfiction successful our Knowledge Base that shows you how to usage Traffic Analytics API successful Google Sheets.

Recap

If you privation to stitchery much information astatine a faster gait than the interface, Semrush API is your cleanable solution.

Adding the modular API to your subscription is disposable aft subscribing to the Business level and volition assistance you entree to our Analytics API, Projects API, and Accounts API. These APIs volition fto you propulsion probe information connected your competitor’s hunt performance, keyword research, and physique awesome advancement dashboards. 

Request API entree here. 

Anyone tin acquisition Semrush Traffic Analytics API - with oregon without a Semrush subscription. This API is astonishing for evaluating markets and imaginable concern partners and investments.

Terms of Use

Before utilizing our API, you request to work and hold to our presumption of use. If you privation to resell our information via API, a abstracted statement indispensable beryllium made. Full presumption of usage tin beryllium recovered here.