Basic docs

Jump to AboutAbout

It’s a group of products with Analytics reports including:

• Domain Analytics
• Organic Research
• Advertising Research
• Keyword Gap Analysis
• Keyword Analytics
• Backlink Analytics

Jump to AuthenticationAuthentication

Request authentication is provided via API keys. An API key is assigned to each user after subscribing to Semrush. You’ll find it in Subscription info > API units. If your API key is unavailable there, refer to How to get API documentation.

Never share your API key publicly. If you share an API call example, replace your key with a placeholder such as https://api.semrush.com/?key=<key>.

Your API key also gives access to your API unit balance. Exposing your credentials can result in your account being compromised, which could lead to unexpected charges.

Jump to Response formatResponse format

All Analytics API Version 3 report endpoints return responses in CSV format.

Jump to ColumnsColumns

Each Semrush Analytics API method supports a set of output columns that determine the data returned in the CSV response.

You can customize your request using the export_columns parameter to include only the fields relevant to your analysis.

The following table indicates:

• Request parameter (the export_columns parameter value)
• Response parameter (the column name in the CSV report)
• Description of what each column represents
• Possible values to help interpret the results (if applicable)
• API methods where the columns are used

Jump to Tips and tricksTips and tricks

• Column names can’t be changed
• The order of columns can be changed
• The number of columns can be increased
• Semrush will only remove old columns after notifying users

Jump to DatabasesDatabases

Regional database types:

• Desktop: Specified as a two-letter code.
• Mobile: Specified as a two-letter code with the mobile- prefix.
• Extended: Specified as a two-letter code with the -ext suffix.

Mobile and extended databases aren’t available for any requests in the Keyword reports.

Jump to Error messagesError messages

Jump to FiltersFilters

To apply filters to a report, add the display_filter parameter with a URL-encoded string that contains filters separated by | (%7C). Max. number of filters that can be applied at once is 25.

A single filter consists of <sign>|<field>|<operation>|<value>, where:

• <sign>: + (%2B) or - (%2D) to include or exclude the corresponding data.
• <field>: Possible fields are listed in the tables in the upcoming sections.
• <operation>: Possible operations are listed in the Operations section and depend on the field type.
• <value>: Possible values depend on the field.

Some ready-to-use functions might encode the + sign incorrectly. Make sure that it’s encoded as %2B.

Jump to Example requestsExample requests

https://api.semrush.com/?type=phrase_related&key=YOUR_API_KEY&phrase=seo&export_columns=Ph,Nq,Cp,Co,Nr,Td,Rr,Fk&database=us&display_limit=10&display_sort=nq_desc&display_filter=%2B%7CNq%7CLt%7C1000

https://api.semrush.com/?type=domain_organic&key=YOUR_API_KEY&display_limit=10&export_columns=Ph,Po,Pp,Pd,Nq,Cp,Ur,Tr,In,Pp&domain=toyota.com&display_sort=tr_desc&database=us&display_filter=%2B%7CIn%7CEq%7C3%7C%2B%7CPp%7CGt%7C5

Jump to Metric fieldsMetric fields

Jump to Text fieldsText fields

Jump to Fields with fixed valuesFields with fixed values

Jump to OperationsOperations

<operation> can be set depending on the field type.

Jump to For metric fieldsFor metric fields

Jump to For text fieldsFor text fields

Jump to For fields with fixed valuesFor fields with fixed values

Leave the field blank.

Jump to SERP FeaturesSERP Features

The table provides a list of supported SERP features with their codes and descriptions and indicates whether a particular SERP feature includes a direct link to the target domain.

The SERP features codes can be included in the FKn and FPn columns (as listed in Columns table) when making requests to retrieve data on keyword-specific SERP features and their positions. These columns are used with the export_columns parameter; however, not all requests accept FKn and FPn as part of export_columns.

Jump to Example requestExample request

https://api.semrush.com/?key=API_KEY&type=domain_ranks&export_columns=Db,Dn,Rk,Or,Ot,Oc,Ad,At,Ac,Sh,Sv,FK1,FP1&domain=apple.com&database=us

This example retrieves SERP feature data for your domain, where FP1 shows the count of times the domain ranks within a specific SERP feature (in this case, 1 is for Knowledge panel), and FK1 shows the total occurrences of this feature for keywords the domain ranks for, whether or not the domain appears in it.

Jump to SortingsSortings

You can sort the response results by different parameters in ascending or descending order.

To set the sorting in an Analytics report request, include the display_sort parameter with the target sorting rule. You can set only one sorting rule per request.

For example, you can sort keywords by traffic share in descending order in the Domain Organic Search Keywords request:

https://api.semrush.com/?type=domain_organic&key=YOUR_API_KEY&display_filter=%2B%7CPh%7CCo%7Cseo&display_limit=10&export_columns=Ph,Po,Pp,Pd,Nq,Cp,Ur,Tr,Tc,Co,Nr,Td&domain=seobook.com&display_sort=tr_desc&database=us

Jump to Historical dataHistorical data

Most analytic reports let you download historical data.

Historical data costs more than regular data requests. For example, in the Domain Overview (all databases) report, the historical data cost 50 API units per line while the current data is 10 API units per line.

To check the historical data price, click the icon next to the regular request price:

Some reports, like Domain Overview (history), provide only historical data. For these reports, the displayed request price already applies to historical data.