docs.md

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"