This feature is available only if your plan has it included or if you have purchased an API add-on. Making requests is otherwise blocked, even if you have a valid API KEY.
With API requests, you can automate query creation, get shareable links and analyze data without accessing our Surfer web app through a graphical interface.
API currently interacts with:
All examples of the below requests are formatted to the Linux version of the cURL command - if you'd like to use it on a Windows machine, you have to adjust the syntax first.
If you'd prefer to see an example of a JSON request - alternate documentation is available in this document.
Authentication
Surfer API uses API keys to authenticate requests. If you'd like to get your API key, please contact support via Live Chat or mail us directly at [email protected].
The API key must be included with each request in the API-KEY header. Sending requests without a proper API key or appropriate plan tier will result in a response of Access Denied.
Content Editor
Content Editor provides endpoints to:
create a query
get public hash/permalink for query access
add a custom keyword to guidelines
Create a query
Schedules a new query.
The limit is defined by your plan.
In-app equivalent (Content Editor dashboard -> Create Content Editor):
URL
/api/v1/content_editors
Method
POST
Parameters
JSON body with the following keys:
keywords (required)
location
word_count
Example
Request:
curl -X POST 'https://app.surferseo.com/api/v1/content_editors' -H 'API-KEY: <your key>' -H 'Content-Type: application/json' --data-raw '{
"keywords": ["seo research","seo article optimization"],
"location": "United States"
}'Response:
{
"state": "scheduled",
"permalink_hash": "kKi7n3pkRk7Gw5cxKDiBAbCAybnDTt2z",
"id": 5632898
}
Get query permalink
Get the state of the query and hash that is used for generating publicly-accessible links.
In-app equivalent (Content Editor dashboard -> Any Content Editor query -> Share):
URL
/api/v1/content_editors/:id
Method
GET
Parameters
JSON body with the following keys:
id (required)
Example
Request:
curl -X GET 'https://app.surferseo.com/api/v1/content_editors/4141997' -H 'API-KEY: <your key>'
Response:
{
"state": "completed",
"permalink_hash": "zJ_yuVSZMaGrw7b-SI7WKfNtgaR2fNZY",
"id": 4141997
}
Add keywords
Add additional keywords to Surfer's guidelines (synonymous with Import Bulk Terms from Editor's Customize menu).
In-app equivalent (Any Content Editor query -> Customize -> Terms -> Bulk import terms):
URL
/api/v1/content_editors/:id
Method
PATCH
Parameters
JSON body with the following keys:
id (required)
included_terms
Example
Request:
curl -X PATCH 'https://app.surferseo.com/api/v1/content_editors/4141997' -H 'API-KEY: <your key>' -H 'Content-Type: application/json' --data-raw '{
"included_terms":["seo is best", "seo application", "seo help"]
}'Response:
OK
Audit
Audit provides endpoints to:
create a query
get URLs and Content Scores of both audited URL and selected competitors
Create a query
Schedules a new query.
Limit is defined by your plan.
In-app equivalent (Audit dashboard -> Create Audit):
URL
/api/v1/audits
Method
POST
Parameters
JSON body with the following keys:
keywords (required)
url (required)
cache
device
location
Example
Request:
curl -X POST 'https://app.surferseo.com/api/v1/audits' -H 'API-KEY: <your key>' -H 'Content-Type: application/json' --data-raw '{
"device": "mobile",
"keyword": "seo research",
"location": "United States",
"url": "https://yourAuditedPage.com/"
}'Response:
{
"state": "scheduled",
"id": 767429
}
Get a query
For a given query ID returns a list of URLs and Content scores for audited URL and selected competitors.
In-app equivalent (Any Audit query -> Select competitors):
URL
/api/v1/audits/:id
Method
GET
Parameters
JSON body with the following keys:
ID parameter which you can get from webpage URL or from Create a query's response (required)
Example
Request:
curl -X GET 'https://app.surferseo.com/api/v1/audits/482473' -H 'API-KEY: <your key>'
Response:
{
"state": "completed",
"id": 482473,
"competitors_pages": [
{
"url": "https://www.competitor1.com/",
"content_score": 64
},
{
"url": "https://www.competitor2.com/",
"content_score": 49
},
{
"url": "https://www.competitor3.com/",
"content_score": 55
},
{
"url": "https://www.competitor4.com/",
"content_score": 78
},
{
"url": "https://www.competitor5.com/",
"content_score": 48
}
],
"audited_page": {
"url": "https://www.auditedURL.com/",
"content_score": 81
}
}
SERP Analyzer
SERP Analyzer provides endpoints to:
create a query
create a batch of queries
list queries
Create a query
Schedules a new query.
(Fair Use policy limit applies, by default 100 queries a day.)
In-app equivalent (SERP Analyzer dashboard -> Create SERP Analyzer):
URL
/api/v1/serp_analyzer
Method
POST
Parameters
JSON body with the following keys:
keyword (required)
location (required)
analyze_nlp_entities
analyze_nlp_sentiment
analyze_nlp_entity_sentiment
mobile
screenshot
Supported locations are available at https://app.surferseo.com/api/v1/locations. This endpoint does not require authentication.
Example
Request:
curl -H 'Content-Type: application/json' -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/serp_analyzer --data \ '{"keyword": "seo keyword", "location": "United States", "mobile": true}'
Response:
{
"state": "scheduled",
"id": 2117453
}
Create a batch of queries
Schedules a batch of queries.
(Fair Use policy limit applies, by default 100 queries a day.)
In-app equivalent (SERP Analyzer dashboard -> Create SERP Analyzer):
URL
/api/v1/serp_analyzer/batches
Method
POST
Parameters
JSON body with an array of SERP Analyzer requests. Each query should have the same structure as when scheduling individual query.
Example
Request:
curl -H 'Content-Type: application/json' -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/serp_analyzer/batches --data \ '[{"keyword": "api seo", "location": "United States"}, {"keyword": "seo life", "location": "Poland"}]'
Response:
[
{
"state": "scheduled",
"id": 2117448
},
{
"state": "scheduled",
"id": 2117449
}
]
List queries (CSV export)
Returns a CSV-style list of SERP queries.
List contains up to 5000 entries from the last month.
In-app equivalent (SERP Analyzer dashboard):
URL
/api/v1/exports/csv/serp_analyzer
Method
GET
Parameters
None
Example
Request:
curl -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/exports/csv/serp_analyzer
Response:
"id","state","created","location","keyword"
"25416","completed","2020-11-03 15:03:29Z","United States","move reviews"
"25413","completed","2020-11-03 13:56:23Z","United States","seo for experts"
"25411","completed","2020-11-03 13:55:37Z","United States","how to invest"
"25410","completed","2020-11-03 13:27:30Z","United States","iphone cases"
Search results
Returns search results for a given query. The report contains URLs with SERP data, keywords and factors calculated by Surfer.
The data here highlights important page characteristics and provides high-level overview of SERP quality.
In-app equivalent (Any SERP Analyzer query -> Chart data + Search Results tab):
URL
/api/v1/exports/csv/serp_analyzer/:id/search_results
Method
GET
Parameters
ID is a parameter you can get from CSV export
Example
Request:
curl -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/exports/csv/serp_analyzer/960173/search_results
Response:
"position","url","state","title/keywordCount/all","title/keywordCount/outsideLinks","meta_description/keywordCount/all","meta_description/keywordCount/outsideLinks","url/path/keywordCount/all","url/domain/keywordCount/all","body/wordCount/all","body/wordCount/outsideLinks","body/keywordCount/all","body/keywordCount/outsideLinks","p/wordCount/all","p/wordCount/outsideLinks","p/keywordCount/all","p/keywordCount/outsideLinks","p/elementCount/all","p/elementCount/outsideLinks","headings/wordCount/all","headings/wordCount/outsideLinks","headings/keywordCount/all","headings/keywordCount/outsideLinks","headings/elementCount/all","headings/elementCount/outsideLinks","above_the_fold/wordCount/all","above_the_fold/wordCount/outsideLinks","above_the_fold/keywordCount/all","above_the_fold/keywordCount/outsideLinks","h1/keywordCount/all","h1/keywordCount/outsideLinks","h2/keywordCount/all","h2/keywordCount/outsideLinks","h3/keywordCount/all","h3/keywordCount/outsideLinks","h4/keywordCount/all","h4/keywordCount/outsideLinks","h5/keywordCount/all","h5/keywordCount/outsideLinks","h6/keywordCount/all","h6/keywordCount/outsideLinks","h1/elementCount/all","h1/elementCount/outsideLinks","h2/elementCount/all","h2/elementCount/outsideLinks","h3/elementCount/all","h3/elementCount/outsideLinks","h4/elementCount/all","h4/elementCount/outsideLinks","h5/elementCount/all","h5/elementCount/outsideLinks","h6/elementCount/all","h6/elementCount/outsideLinks","img_alt/keywordCount/all","img_alt/keywordCount/outsideLinks","img_alt/wordCount/all","img_alt/wordCount/outsideLinks","img/elementCount/all","img/elementCount/outsideLinks","strong_and_b/wordCount/all","strong_and_b/wordCount/outsideLinks","strong_and_b/keywordCount/all","strong_and_b/keywordCount/outsideLinks","strong_and_b/elementCount/all","strong_and_b/elementCount/outsideLinks","score/content/all","pageSpeed/ttfb/all","pageSpeed/totalSize/all","pageSpeed/load/all"
"1","https://test.com/","completed","0","0","0","0","0","1","426","347","9","9","195","195","1","1","0","0","33","0","0","0","0","0","47","47","5","5","3","3","0","0","0","0","0","0","0","0","0","0","12","12","0","0","0","0","0","0","0","0","0","0","0","0","2","1","19","18","0","0","0","0","0","0","15","1589","553.0595703125","3013"
"2","https://www.speedtest.net/","completed","1","1","0","0","0","1","277","83","3","0","57","51","0","0","3","3","9","4","0","0","3","3","35","18","1","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","3","3","0","0","0","0","0","0","0","0","13","0","2","0","5","0","0","0","1","0","14","166","1255.7548828125","2443"
...[up to 50 SERP positions in total, depending on the exact keyword]
Prominent terms
Returns prominent terms and phrases for a given query. The report includes counters for words, phrases, and their density.
In-app equivalent (Any SERP Analyzer query -> Prominent words and phrases tab -> Phrases):
URL
/api/v1/exports/csv/serp_analyzer/:id/prominent_terms
Method
GET
Parameters
ID is a parameter you can get from CSV export
Example
Request:
curl -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/exports/csv/serp_analyzer/960173/prominent_terms
Response:
"term","pages","density_min","density_avg","density_max","words_min","words_avg","words_max"
"graphic designers","5","0.0","0.0","0.01","2.0","4.25","7.0"
"ai tool","4","0.0","0.0","0.0","2.0","3.5","5.0"
"graphic design","5","0.0","0.01","0.02","4.0","16.57","37.0"
"ai tools","5","0.0","0.01","0.06","2.0","5.86","11.0"
"ai design","9","0.0","0.0","0.01","2.0","8.2","22.0"
"design tool","6","0.0","0.0","0.0","2.0","5.78","14.0"
"ai software","5","0.0","0.0","0.01","2.0","7.0","11.0"
"adobe sensei","5","0.01","0.01","0.01","12.0","12.0","12.0"
"machine learning","6","0.0","0.0","0.01","4.0","8.71","20.0"
"based design","5","0.0","0.0","0.0","4.0","4.0","4.0"
"design tools","8","0.0","0.0","0.0","2.0","5.83","19.0"