SEOmonitor API Documentation

Introduction

The SEOmonitor API allows you to programmatically access keyword ranking, traffic, and other SEO data from the SEOmonitor platform. You can use the API to build custom reports, automate workflows, and integrate SEOmonitor data into your own applications.
The API enables free and unrestricted access to all your data in the platform, for all Tracked Campaigns. Additionally, it provides access to SEOmonitor's curated UK and US keyword database.

Main Capabilities
These are the main data sets you can retrieve with the API 3.0 endpoints:

• Campaign-level data: Campaign details and campaign-wide keyword data, landing page data, groups data, traffic data, forecast data, or campaign website research data.
• Keyword-level data: Data for any and all keywords in the campaign, including ranking data, search data, SERP data, competitor data, SEO Opportunity, keyword-level traffic data, and keyword-level forecast projections data.
• Keyword group-level data: Data for any keyword group in the campaign, including aggregated search and SERP data, website Visibility on specific groups, group SEO Opportunity data.
• Landing page-level data: Data for the ranking landing pages of requested keywords in the campaign, including ranking data and search intent. Data for requested landing pages, including aggregated search and SERP data, SEO Opportunity, and landing page Visibility.
• Organic traffic data: Data for the website's organic sessions, conversions, and revenue, including traffic data by segments (brand, non-brand, all traffic, and custom user-created traffic segments), and by specific keywords.
• Keyword & website research data: Data for any keyword in SEOmonitor's Research database – any domain-level aggregated search, SERP, and ranking data, and keyword-level and keyword list-level metrics, for the tracked website and for any competitor in top 100.
• Forecast data: Overview data and details for specific Forecast Scenarios and Objectives, and keyword-level forecast data.

Getting Started
Log into your SEOmonitor account and retrieve your unique API Token (Account Settings > Edit Profile).

• Check out the Quick Start Guide to learn how to make your first API call.
• Read through the Authentication Guide to learn how to properly authenticate your API requests.

Libraries and SDKs
SEOmonitor API uses HTTP protocol, which allows the application of our API to almost all programming languages. All the responses are returned in JSON format by default.
For convenience, we offer client libraries for popular programming languages:

• JavaScript
• PHP
• Python
• Java

Changelog
This is the first version of API 3.0. The Changelog page will be updated as we continue to develop new features and improvements.

The previous version API 1.2 continues to be functional. You can use both API versions according to your needs. But API 1.2 will not undergo regular maintenance and enhancements.

Authentication Guide

You can test the APIs directly on the documentation page of the respective endpoint, by clicking on Try it out.

To authenticate the requests with your API key, you can set the environment variable Authorization with your API Key. To do this, on the Try it out sidebar, click on Go to set value.

Alternatively, go to the Auth tab. Under Type, select API Key, and Add to the Headers, the Key 'Authorization' and the Value, your API key.

If you're using any other tool to test the APIs, add the 'Authorization' key to the request header with your API key (see a cURL example in the Quick Start Guide).

Quick Start Guide

This guide provides a quick walkthrough of how you can make your first API request.

Get your API key

First, you'll need to get an API key:

1. Log in to your SEOmonitor account (https://app.seomonitor.com)
2. Go to Account Settings > Edit Profile
3. Copy the API Token to use in your API requests

Note: Clicking "Regenerate API Token" will overwrite the current key and you will lose access if you or other users are currently using it.

Make a request

You can use any tool that supports HTTP request-response to make API requests, or directly try them on the documentation page of the respective endpoint, using the Try it out option. Let's take a quick look at both.

For this example, let's use cURL from any Command Line Interface (CLI) tool like Terminal, to make a request to get Tracked Campaigns:

curl --request GET \ --url https://apigw.seomonitor.com/v3/dashboard/v3.0/campaigns/tracked \ --header 'Accept: application/json' \ --header 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzZW9tb25pdG9yLmNvbSIsImlhdCI6MTY1Mjc4NTcwNCwidXNlcl9pZCI6IjY2NTI5In0.2_l9e7ohs9QHbwmr48mIoEF-QxZHNPFiAzJbMk00jcB'

This will retrieve the Tracked Campaigns data for an SEOmonitor account having the following API Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzZW9tb25pdG9yLmNvbSIsImlhdCI6MTY1Mjc4NTcwNCwidXNlcl9pZCI6IjY2NTI5In0.2_l9e7ohs9QHbwmr48mIoEF-QxZHNPFiAzJbMk00jcB.

Let's break down the parts of the request:

• --request GET - Make a GET request
• --url - The API endpoint URL
• --header - Adds the Authorization header with your API key

Handle the response

The API will return a JSON response like this:

{ "campaign_info": { "id": "74516", "name": "Asos.com", "company": "Asos", "company_id": "51256", "domain": "www.asos.com", "keyword_count": 588, "date_created": "2023-04-25", "location": "United Kingdom", "currency": "EUR", "mrr": 3000 }, "visibility": { "desktop": { "latest": 0.28, "trend_7days": 0.2, "trend_30days": 0.2 }, "mobile": { "latest": 0.27, "trend_7days": 0.2, "trend_30days": 0.2 } }, "multiple_locations": [ { "campaign_id": 12746, "location": "London, United Kingdom", "visibility": { "desktop": { "latest": 0.32, "trend_7days": 0.02 "trend_30days: 0.1 }, "mobile": { "latest": 0.33, "trend": 0.03 "trend_30days": 0.1 } } } } ], "health_status": "healthy", "objective_status": { "actual_sessions": 78400, "estimated_sessions": 78400, "performance": 1, "status": "on_track", "start_month": "Jun, 2023", "end_month": "Jul, 2024" }, "reporting_status": "submitted", "account_manager": "Jo Hart" }

Alternatively, on the documenation page of Get Tracked Campaigns, click on Try it out.

• Authenticate the request with your API key as shown in the Authentication Guide.
• Input the Company and/or Campaign IDs under the Params tab (see further below to see how you can retrieve these IDs).
• Click on Send.

And that's it! You just made your first API request. Analyze the response, and then check out the rest of the API reference documentation to see what else you can build.

Best practices

• Keep your API key private – do not share your key publicly.
• Do not include your key directly in code that you distribute – use environment variables instead.
• Regenerate your key periodically for improved security.
• Limit API key access to only required endpoints if possible.

Revoking API keys

If your API key is compromised, you can revoke it by regenerating the API Token in your SEOmonitor Account Settings. This will immediately invalidate the current key so further requests can't be made.

For any other issues with authentication, contact our support team.

Retrieve the IDs of the company, campaigns, keywords and keyword groups

The unique IDs of your company, campaigns, keywords, or keyword groups can be retrieved either from the specific URLs of the platform, or from specific API endpoint responses. Further below you'll find details on these alternatives.

Company ID
The company ID can only be retrieved from the platform. Follow these steps:

1. Log in to your SEOmonitor account (https://app.seomonitor.com)
2. Go to Account Settings > Billing
3. In the Billing section, the platform URL contains the company ID.
   E.g.: "app.seomonitor.com/v2/account/company/51244/billing" – in this example, the company ID is "51244"

Campaign ID
To retrieve the campaign ID from the platform, follow these steps:

1. Log in to your SEOmonitor account (https://app.seomonitor.com)
2. Open the required campaign by clicking on its name in the Agency Dashboard.
3. By default, the campaign opens in the Rank Tracker view. The platform URL contains the company ID.
   E.g.: "https://app.seomonitor.com/v2/72416/manage/strategy/0/desktop/keywords?timeframe=2023-09-04%3A2023-10-04" – in this example, the campaign ID is "72416".

To retrieve the campaign ID through the API, make a call through the Get Tracked Campaigns Details endpoint. The response will contain the details of the requested Tracked Campaigns, including their IDs, which you can further use in other endpoint requests.

Keyword ID
To retrieve the keyword ID from the platform, follow these steps:

1. Log in to your SEOmonitor account (https://app.seomonitor.com)
2. Open the required campaign and click on the required keyword.
3. The platform URL for the keyword view (Keyword Sidebar) contains the keyword ID.
   E.g.: "https://app.seomonitor.com/v2/72416/manage/strategy/0/desktop/keywords?timeframe=2023-09-04%3A2023-10-04&ksid=7063139" – in this example, the keyword ID is "7063139"

To retrieve the keyword ID through the API, make a call through the Get Keyword Data endpoint. The response will contain the details of the requested keywords, including their IDs, which you can further use in other endpoint requests.

Keyword Group ID

1. Log in to your SEOmonitor account (https://app.seomonitor.com)
2. Open the required campaign and click on the required keyword group (Groups side-menu).
3. The platform URL for the keyword group view contains the keyword ID.
   E.g.: "https://app.seomonitor.com/v2/72416/manage/strategy/69976/desktop/keywords?timeframe=2023-09-04%3A2023-10-04" – in this example, the keyword group ID is "69976"

To retrieve the keyword group ID through the API, make a call through the Get Groups List endpoint. The response will contain the details of the requested keyword groups, including their IDs, which you can further use in other endpoint requests.

Forecast ID for Scenarios or Objectives

1. Log in to your SEOmonitor account (https://app.seomonitor.com)
2. Open the required campaign and go to Forecast from the main menu (top).
3. Select a Scenario or the Objective (if set). The platform URL for the specific scenario contains the forecast ID.
   E.g.: "https://app.seomonitor.com/v2/forecast/118794/3788" – in this example, the forecast ID is "3788"

To retrieve the forecast ID through the API, make a call through the Get Forecast Scenarios endpoint. The response will contain the details of the requested Scenario or Objective, including their IDs, which you can further use in other endpoint requests.

SERP Feature Abbreviations
The returned data for some endpoints will contain SERP feature names in abbreviated form.
The returned values for SERP features are abbreviated as follows:

• "aio": AI Overview
• "aib": AI Button
• "adt": Ads Pack Top
• "def": Definitions
• "dir": Directions
• "fsn": Featured Snippet
• "flt": Flights
• "htl": Hotels
• "img": Images Pack
• "job": Jobs
• "kng": Knowledge Graph
• "geo": Local Pack
• "shp": Product listing
• "rcp": Recipes
• "qns": Questions
• "new": Top Stories
• "vid": Video Carousel
• "app": Apps
• "prd": Product Grid
• "plc": Places
• "pls": Places Sites
• "tst": Top Sights Grid
• "vdi": Visual Digest
• "dan": Direct Answer
• "fla": Flights Airlines
• "fls": Flights Sites
• "ttk": Things to know

Rate Limits

There are request limits in place to prevent abuse and ensure fair usage.

Exceeding the request limits will lead to HTTP 429 responses. If you need higher limits, contact our support team.

Limits & Quotas

Limit	Number of requests
Maximum requests per second	10
Maximum rows per request (Request Quota)	1000
Daily Quota	10 000

**Exceeding Limits **

If you exceed the rate limits, you will receive a 429 Too Many Requests response.

Daily Quota Exceeded

{ "error": { "message": "Daily quota exceeded", "details": [ "You have exceeded the allowed daily requests" ] } }

Details:
This error message indicates that the request exceeds the rate limits for daily requests. Retry the request after some delay.

Rate Limit Exceeded

{ "error": { "message": "Rate limit exceeded", "details": [ "You have exceeded the allowed requests per second" ] } }

Details:
This error message indicates that the request exceeds the rate limits for requests per second. Retry the request after some delay.

Need Higher Limits?

The default limits allow most normal API usage patterns. For most use cases, these limits are sufficient. But if you require higher limits, please contact our support team.

Provide details on:

• Your specific use case
• The endpoints you are using
• The increased limits you are looking for

We will review your request and adjust limits where appropriate.

Errors

SEOmonitor API uses standard HTTP response codes to indicate the success or failure of API requests.

HTTP Status Codes

Code	Description
200	Success
400	Bad request - the request was malformed or missing required parameter
401	Unauthorized - invalid or missing API key
403	Forbidden - API key does not have access to the requested resource
404	Not found - the requested resource does not exist
429	Too many requests - rate or quota limit exceeded
500	Internal server error - an unexpected error on the API server
50x	Errors specific to various endpoints

Error Response Format

Error responses will be returned in JSON format:

{ "error": { "message": "Rate limit exceeded", "details": [ "You have exceeded the allowed requests per second" ] } }

The error object contains:

• message - A general error message
• details - More specific details about the error

Common Errors

401 Unauthorized

{ "error": { "message": "Invalid authentication", "details": [ "The API key provided is invalid" ] } }

Details:
This error message indicates there is a problem with the API key:

• The API key is missing from the request
• The key is invalid or incorrect
• The key is expired or revoked

Check that you are sending the correct API key in the Authorization header.

403 Forbidden

{ "error": { "message": "Forbidden access", "details": [ "Your API key does not have access to the requested data" ] } }

Details:
This error message indicates that the API key being used does not have access to perform the requested operation. Ensure the key has the required scopes enabled.

404 Not Found

{ "error": { "message": "Data not found", "details": [ "The requested data does not exist." ] } }

Details:
This error message indicates that the object specified by the request does not exist. For example, requesting a keyword that is not in your SEOmonitor account.

429 Too Many Requests

Daily Quota Exceeded

{ "error": { "message": "Daily quota exceeded", "details": [ "You have exceeded the allowed daily requests" ] } }

Details:
This error message indicates that the request exceeds the rate limits for daily requests. Retry the request after some delay.

Rate Limit Exceeded

{ "error": { "message": "Rate limit exceeded", "details": [ "You have exceeded the allowed requests per second" ] } }

Details:
This error message indicates that the request exceeds the rate limits for requests per second. Retry the request after some delay.

500 Internal Server Error

{ "error": { "message": "Internal server error", "details": [ "The server encountered an error while processing your requests" ] } }

Details:
This error message indicates that an unexpected error occurred on the API server. Try the request again later. If the issue persists, contact support.

50X Endpoint-specific errors
You may encounter errors on specific endpoint requests – these are listed and explained under each endpoint page.

Changelog

Version 3.0 (current)

Release Date: 01 Feb 2024
This is the first version of the API 3.0.

Version 1.2 (previous functional version)

Contact us

Need help using the API, or have general inquiries? Please contact our support team via chat (click on Contact us on the SEOmonitor platform), or via email.