Skip to content

Instantly share code, notes, and snippets.

@robuye

robuye/docs.md Secret

Last active Nov 17, 2020
Embed
What would you like to do?

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"
    
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment