In the below article, you will find details about Surfer API.

This feature is available from the Business plan and above.

With API requests, you can automate query creation, get shareable links and analyze data without accessing our Surfer web app though a graphical interface.
API currently interacts with:

All examples of the below requests are formatted to Linux version of 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 is must be included with each request in API-KEY header.

Sending requests without 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 custom keyword to guidelines

Create a query

Schedules a new query.

The limit is defined by your plan.

  • 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 state of the query and hash that is used for generating publicly-accessible link.

  • 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 to Import Bulk Terms from Editor's Customize menu).

  • 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.

  • 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.

  • 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.)

  • 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.)

  • 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 1000 entries from the last month.

  • 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.

  • 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.

  • 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"
Did this answer your question?