Add Rank Tracker Keywords
const url = 'https://sitechecker.pro/api/v1/keywords';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"project_id":123,"keywords":["buy shoes","shoe store"],"geos":[{"country_code":"US","language_code":"en","search_engine":"google","device":"desktop","location":"New York,New York,United States"},{"country_code":"GB","language_code":"en"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://sitechecker.pro/api/v1/keywords \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "project_id": 123, "keywords": [ "buy shoes", "shoe store" ], "geos": [ { "country_code": "US", "language_code": "en", "search_engine": "google", "device": "desktop", "location": "New York,New York,United States" }, { "country_code": "GB", "language_code": "en" } ] }'Starts tracking keywords in an existing project. Every keyword is tracked in every geo: the request creates keywords × geos tracked keywords (at most 500 pairs per request, 100 keywords and 10 geos). Keywords are trimmed, lower-cased and deduplicated. Pairs the project already tracks are not duplicated: they are returned with created=false, so a retried request is safe and always answers 200. New pairs count towards the plan keyword limit; when the request would exceed it, nothing is added and the answer is 403 QUOTA_EXCEEDED. Positions appear after the next rank check — read them with GET /api/v1/keywords. Valid geo values come from GET /api/v1/rank_tracker_countries, /rank_tracker_languages and /rank_tracker_locations. All invalid keywords and geo fields are reported together in one 422.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Keywords to track, up to 100, each up to 255 characters.
Where to track every keyword, up to 10.
Where and how a keyword is tracked. Codes are case-insensitive. Valid values come from GET /api/v1/rank_tracker_countries, /rank_tracker_languages and /rank_tracker_locations.
object
ISO 3166-1 alpha-2 country code.
ISO 639-1 language code.
Mobile is available for google only.
Optional Google location: a location_name or location_id from GET /api/v1/rank_tracker_locations. Omit or send an empty string to track the whole country. Google only.
Example
{ "project_id": 123, "keywords": [ "buy shoes", "shoe store" ], "geos": [ { "country_code": "US", "language_code": "en", "search_engine": "google", "device": "desktop", "location": "New York,New York,United States" }, { "country_code": "GB", "language_code": "en" } ]}Responses
Section titled “Responses”Every requested keyword × geo pair, new and already tracked
object
object
A requested keyword × geo pair and whether this request started tracking it.
object
ID of the tracked keyword: one keyword in one geo. Pass it to GET /api/v1/keywords, GET /api/v1/keyword_daily_positions, GET /api/v1/serp_snapshot and DELETE /api/v1/keywords.
Keyword as stored: trimmed and lower-cased.
Opaque location id; null when the whole country is tracked.
Canonical Google location name; null when the whole country is tracked.
True when this request added the pair; false when the project already tracked it.
object
Pairs this request started tracking.
Pairs the project already tracked.
Example
{ "data": { "project_id": 123, "tracked_keywords": [ { "tracked_keyword_id": 987654, "keyword": "buy shoes", "search_engine": "google", "device": "desktop", "country_code": "US", "country_name": "United States", "language_code": "en", "language_name": "English", "location_id": "loc_TmV3IFlvcmssTmV3IFlvcmssVW5pdGVkIFN0YXRlcw", "location_name": "New York,New York,United States", "created": true } ] }, "meta": { "created": 3, "existing": 1 }}Missing or invalid API key
Returned as INVALID_API_KEY when the key is missing or unknown, and as REVOKED_API_KEY when the key exists but was revoked — the latter needs a new key.
object
object
Example
{ "error": { "code": "INVALID_API_KEY", "message": "Invalid or missing API key." }}No active API entitlement, view-only access to the project (ACCESS_DENIED), or the plan keyword limit would be exceeded (QUOTA_EXCEEDED, see ErrorQuotaExceeded)
Returned as MISSING_PUBLIC_API_ACCESS when the account has no active API entitlement, as ACCESS_DENIED when the project is shared with the account at an access level that does not allow this request (a project of another account is reported as 404 PROJECT_NOT_FOUND instead), and as ACCOUNT_BLOCKED or ACCOUNT_INACTIVE when the account behind a valid key is blocked or deactivated — a new key will not help, contact support@sitechecker.pro.
object
object
Returned as QUOTA_EXCEEDED when a write would take the account over a plan limit (for example, the number of projects). Free capacity first, or upgrade the plan.
object
object
Example
{ "error": { "code": "MISSING_PUBLIC_API_ACCESS", "message": "API access is not available: the account has no active API entitlement." }}Project not found
The exact missing resource is in error.code: PROJECT_NOT_FOUND, SEGMENT_NOT_FOUND, CRAWL_NOT_FOUND, KEYWORD_NOT_FOUND, OPPORTUNITY_NOT_FOUND, SNAPSHOT_UNAVAILABLE or NOT_FOUND. A project that belongs to another account is reported as PROJECT_NOT_FOUND, so its existence is not disclosed.
object
object
Example
{ "error": { "code": "PROJECT_NOT_FOUND", "message": "Project not found." }}Validation error: every invalid keyword and geo field is listed in details
Rejected query parameters. error.code is VALIDATION_ERROR for parameter validation (including a query parameter the endpoint does not accept), or INVALID_DATE_RANGE / INVALID_FILTER / INVALID_EVENT_TYPE / UNSUPPORTED_FILTER / UNSUPPORTED_DIMENSION / UNSUPPORTED_METRIC / UNSUPPORTED_SCOPE / SEGMENT_FILTER_UNSUPPORTED for module-specific rules. Request-body validation errors also carry error.details, listing every invalid field.
object
object
object
Every invalid field, not only the first one repeated in error.message. Present on request-body validation errors; field is the path inside the body.
object
Path of the invalid field inside the request body, e.g. url, keywords[0], geos[1].country_code.
Example
{ "error": { "code": "VALIDATION_ERROR", "message": "project_id is required." }}Rate limit exceeded — retry after the interval in the Retry-After header
object
object
Example
{ "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Try again later." }}Internal server error
object
object
Example
{ "error": { "code": "INTERNAL_ERROR", "message": "Internal server error." }}