All Collections
Other
Surfer API Documentation
Surfer API Documentation

BETA version of Surfer available via API - create queries without accessing your dashboard!

Aleksandra Wojcik avatar
Written by Aleksandra Wojcik
Updated over a week ago

This feature is available only if your plan has it included or if you have purchased an API add-on. Making requests is otherwise blocked, even if you have a valid API KEY.

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

  • Content Editor

  • Audit

  • SERP Analyzer

All examples of the below requests are formatted to the Linux version of the cURL command - if you'd like to use it on a Windows machine, you have to adjust the syntax first.

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 must be included with each request in the header as API-KEY field.
Sending requests without a proper API key or without appropriate plan or add-on will result in a response of 401 "Access Denied".

Testing and sandbox

We currently do not have a sandbox environment where you could test your requests.

Every query you create via API will count towards your actual account quotas.

Similarly - having API access doesn't automatically grant you access to all tools.
If your plan doesn't have Audit or SERP Analyzer included - you won't be able to create queries using API.

Content Editor

Content Editor provides endpoints to:

  • create a query

  • get public hash/permalink for query access

  • add a custom keyword to guidelines

Create a query

Schedules a new query.

  • In-app equivalent (Content Editor dashboard -> Create Content Editor):

  • URL

    /api/v1/content_editors

  • Method

    POST

  • Parameters

    JSON body with the following keys:

    • keywords (required)

    • location

    • word_count

    Supported locations are available at https://app.surferseo.com/api/v1/locations. This endpoint does not require authentication.

  • Limit/Cost
    Each successful request will create one query - each query counts against your monthly/yearly limit of Content Editor queries and consumes one credit, regardless of the number of keywords specified for one analysis.

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

  • In-app equivalent (Content Editor dashboard -> Any Content Editor query -> Share):

  • URL

    /api/v1/content_editors/:id

  • Method

    GET

  • Parameters

    JSON body with the following keys:

    • id (required)

  • Limit/Cost

    None

  • 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 to Guidelines

Add additional keywords to Surfer's guidelines (synonymous with Import Bulk Terms from Editor's Customize menu).

  • In-app equivalent (Any Content Editor query -> Customize -> Terms -> Bulk import terms):

  • URL

    /api/v1/content_editors/:id

  • Method

    PATCH

  • Parameters

    JSON body with the following keys:

    • id (required)

    • included_terms

  • Limit/Cost

    None

  • 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

Using Audit API is available only if you have this tool included in your subscription or bought an add-on.
If tool is not available on your account, even valid requests will result in 422 "Quota exceeded".

Create a query

Schedules a new query.

  • In-app equivalent (Audit dashboard -> Create Audit):

  • URL

    /api/v1/audits

  • Method

    POST

  • Parameters

    JSON body with the following keys:

    • keywords (required)

    • url (required)

    • cache

    • device

    • location

    Supported locations are available at https://app.surferseo.com/api/v1/locations. This endpoint does not require authentication.

  • Limit/Cost

    Each successful request will create one query - each query counts against your monthly/yearly limit of Audit queries and consumes one credit.

  • 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",
    "permalink_hash": "ci3XKL1EhhfX-ktOCs6iKYXRv-Umtmf1",
    "id": 767429
    }

Get a query

For a given query ID returns a list of URLs and Content scores for audited URL and selected competitors.

  • In-app equivalent (Any Audit query -> Select 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)

  • Limit/Cost

    None

  • Example

    Request:

    curl -X GET 'https://app.surferseo.com/api/v1/audits/482473' -H 'API-KEY: <your key>'

    Response:

    {
    "state": "completed",
    "permalink_hash": "ci3XKL1EhhfX-ktOCs6iKYXRv-Umtmf1",
    "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

  • get SERP competitors and data about their HTML content

  • get prominent terms from SERP competitors

Using SERP Analyzer API is available only if you have this tool included in your subscription or bought an add-on.
If tool is not available on your account, even valid requests will result in 500 "Internal server error".

Create a query

Schedules a new query.

(Fair Use policy limit applies, by default 100 queries a day.)

  • In-app equivalent (SERP Analyzer dashboard -> Create SERP Analyzer):

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

  • Limit/Cost

    Each query created will count against your daily SERP Analyzer limit (Fair Use policy limit applies, by default 100 queries a day).

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

  • In-app equivalent (SERP Analyzer dashboard -> Create SERP Analyzer):

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

  • Limit/Cost

    Each query created will count against your daily SERP Analyzer limit (Fair Use policy limit applies, by default 100 queries a day).

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

  • In-app equivalent (SERP Analyzer dashboard):

  • URL

    /api/v1/exports/csv/serp_analyzer

  • Method

    GET

  • Parameters

    None

  • Limit/Cost

    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"
    "2871118","scheduled","2023-07-31 22:03:52Z","United States","how to build gaming pc"
    "2800997","completed","2023-07-12 13:53:37Z","United States","rustic wedding ideas"
    "2796112","completed","2023-07-11 10:53:21Z","United States","seo keyword"

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.

  • In-app equivalent (Any SERP Analyzer query -> Chart data + Search Results tab):

  • URL

    /api/v1/exports/csv/serp_analyzer/:id/search_results

  • Method

    GET

  • Parameters

    • ID

  • Limit/Cost

    None

  • Example

    Request:

    curl -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/exports/csv/serp_analyzer/2800997/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://www.intel.com/content/www/us/en/gaming/resources/how-to-build-a-gaming-pc.html","completed","0","0","0","0","1","0","8251","7087","0","0","5022","4885","0","0","134","134","214","139","0","0","34","34","81","68","0","0","0","0","0","0","0","0","0","0","0","0","0","0","1","1","18","18","14","14","2","2","0","0","0","0","0","0","215","205","40","38","108","92","0","0","37","37","77","99","4139.0771484375","11186"

    The exact amount of SERP results may vary depending on the specified keyword, location and device type, max top 50 competitors.

    Each row can be considered a "mini-query" with it's own "state", which can be:

    • "scheduled" - crawl and analysis of this specific competitor did not complete yet

    • "failed" - crawl did not succeed, most likely due to timeout, bot block or content paint issue

    • "completed" - crawl completed and populated data fields based on received HTML code

Prominent terms

Returns prominent words and phrases for a given query. The report includes counters for words, phrases, and their density.

  • In-app equivalent (Any SERP Analyzer query -> Prominent words and phrases tab -> Phrases and Words tabs):

  • URL

    /api/v1/exports/csv/serp_analyzer/:id/prominent_terms

  • Method

    GET

  • Parameters

    • ID

  • Limit/Cost

    None

  • Example

    Request:

    curl -H 'API-KEY: <your key>' https://app.surferseo.com/api/v1/exports/csv/serp_analyzer/2800997/prominent_terms

    Response:

    "term","pages","density_min","density_avg","density_max","words_min","words_avg","words_max"
    "pc builds","4","0.0","0.0","0.0","4.0","4.0","4.0"
    "pcie slot","4","0.0","0.0","0.0","5.0","5.0","5.0"
    "gaming performance","5","0.0","0.0","0.0","2.0","4.17","12.0"
    "best gaming","4","0.0","0.0","0.0","2.0","4.4","9.0"
    "may need","6","0.0","0.0","0.0","3.0","3.5","4.0"
    "graphics card","8","0.0","0.0","0.0","5.0","10.11","16.0"
    "graphics cards","6","0.0","0.0","0.0","2.0","2.0","2.0"
    "gaming pc","10","0.0","0.0","0.01","2.0","10.88","53.0"
    "air cooler","4","0.0","0.0","0.0","2.0","2.0","2.0"
    "pc build","7","0.0","0.0","0.01","2.0","5.88","19.0"

    The exact amount of keywords varies depending on the specified keyword and content from Google.
    Prominent Words are only populated if your selected country for the query does not support NLP analysis. With NLP on - prominent words are automatically assembled into phrases.

    Response can only be generated after all URL crawls from search_results endpoint finished with either "completed" or "failed".

Additional resources:

Did this answer your question?