Overview
SEOmonitor API Documentation
Introduction
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.
These are the main data sets you can retrieve with the API 3.0 endpoints:
Log into your SEOmonitor account and retrieve your unique API Token (Account Settings > Edit Profile).
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:
This is the first version of API 3.0. The Changelog page will be updated as we continue to develop new features and improvements.
Authentication Guide
Quick Start Guide
1.
2.
3.
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'
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzZW9tb25pdG9yLmNvbSIsImlhdCI6MTY1Mjc4NTcwNCwidXNlcl9pZCI6IjY2NTI5In0.2_l9e7ohs9QHbwmr48mIoEF-QxZHNPFiAzJbMk00jcB
.--request GET
- Make a GET request--url
- The API endpoint URL--header
- Adds the Authorization header with your API key{
"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"
}
The company ID can only be retrieved from the platform. Follow these steps:
1.
2.
3.
E.g.: "app.seomonitor.com/v2/account/company/51244/billing" – in this example, the company ID is "51244"
To retrieve the campaign ID from the platform, follow these steps:
1.
2.
3.
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 keyword ID from the platform, follow these steps:
1.
2.
3.
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"
1.
2.
3.
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"
1.
2.
3.
E.g.: "https://app.seomonitor.com/v2/forecast/118794/3788" – in this example, the forecast ID is "3788"
The returned data for some endpoints will contain SERP feature names in abbreviated form.
The returned values for SERP features are abbreviated as follows:
Rate Limits
Limit | Number of requests |
---|---|
Maximum requests per second | 10 |
Maximum rows per request (Request Quota) | 1000 |
Daily Quota | 10 000 |
{
"error": {
"message": "Daily quota exceeded",
"details": [
"You have exceeded the allowed daily requests"
]
}
}
This error message indicates that the request exceeds the rate limits for daily requests. Retry the request after some delay.
{
"error": {
"message": "Rate limit exceeded",
"details": [
"You have exceeded the allowed requests per second"
]
}
}
This error message indicates that the request exceeds the rate limits for requests per second. Retry the request after some delay.
Errors
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": {
"message": "Rate limit exceeded",
"details": [
"You have exceeded the allowed requests per second"
]
}
}
message
- A general error messagedetails
- More specific details about the error{
"error": {
"message": "Invalid authentication",
"details": [
"The API key provided is invalid"
]
}
}
This error message indicates there is a problem with the API key:
{
"error": {
"message": "Forbidden access",
"details": [
"Your API key does not have access to the requested data"
]
}
}
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.
{
"error": {
"message": "Data not found",
"details": [
"The requested data does not exist."
]
}
}
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.
{
"error": {
"message": "Daily quota exceeded",
"details": [
"You have exceeded the allowed daily requests"
]
}
}
This error message indicates that the request exceeds the rate limits for daily requests. Retry the request after some delay.
{
"error": {
"message": "Rate limit exceeded",
"details": [
"You have exceeded the allowed requests per second"
]
}
}
This error message indicates that the request exceeds the rate limits for requests per second. Retry the request after some delay.
{
"error": {
"message": "Internal server error",
"details": [
"The server encountered an error while processing your requests"
]
}
}
This error message indicates that an unexpected error occurred on the API server. Try the request again later. If the issue persists, contact support.
You may encounter errors on specific endpoint requests – these are listed and explained under each endpoint page.
Changelog
This is the first version of the API 3.0.
Contact us
Modified at 2024-09-16 11:28:38