We launched the BETA version of Surfer available via API.
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"