We launched the BETA version of Surfer available via API.
This feature is available from the Business plan and above.
Authentication
Surfer API uses API keys to authenticate requests.
The API key is must be included with each request in API-KEY header.
Endpoints
SERP Analyzer
SERP Analyzer provides endpoints to create queries.
Create a query
-
Description
Schedules a new query.
-
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
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}'
Request accepted.
Create a batch of queries
-
Description
Schedules a batch of queries.
-
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
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"}]'
[
{"status":"ok","index":1},
{"status":"ok","index":2}
]
CSV exports
SERP Analyzer
SERP Analyzer provides endpoints to navigate through user queries and retrieve CSV reports.
List user queries
-
Description
Returns SERP queries.
-
URL
/api/v1/exports/csv/serp_analyzer
-
Method
GET
-
Parameters
None
-
Example
curl -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/exports/csv/serp_analyzer
"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
-
Description
Returns search results for a given query. The raport contains urls with SERP data, keyword and factors calculated by Surfer.
The data here highlights important page characteristics and provides high level overview of SERP quality.
-
URL
/api/v1/exports/csv/serp_analyzer/:id/search_results
-
Method
GET
-
Parameters
id is a URL parameter from the SERP Analyzer queries list report.
-
Example
curl -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/exports/csv/serp_analyzer/960173/search_results
"position","url","state","url/path/keywordCount",...
"1","https://www.nerdwallet.com/article/investing/how-to-invest-in-stocks","completed","1",...
"2","https://www.nerdwallet.com/article/investing/how-to-invest-money","completed","1",...
"3","https://www.moneyunder30.com/start-investing-with-little-money","completed","0",...
Prominent terms
-
Description
Returns prominent terms and phrases for a given query. The raport includes counters for words, phrases and their density.
-
URL
/api/v1/exports/csv/serp_analyzer/:id/prominent_terms
-
Method
GET
-
Parameters
id is a URL parameter from the SERP Analyzer queries list report.
-
Example
curl -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/exports/csv/serp_analyzer/960173/prominent_terms
"term","pages","density_min","density_avg","density_max","words_min","words_avg","words_max"
"like retirement","4","0.0","0.0","0.0","3.0","3.0","3.0"
"best way","6","0.0","0.0","0.0","2.0","2.33","3.0"
"investing money","4","0.0","0.0","0.0","2.0","2.5","3.0"
"investing retirement","5","0.0","0.0","0.0","2.0","2.0","2.0"
"mutual fund","7","0.0","0.0","0.01","2.0","4.22","8.0"
"index fund","5","0.0","0.0","0.0","4.0","5.0","7.0"
"retirement account","6","0.0","0.0","0.0","7.0","7.0","7.0"