The TrueRanker API allows you to programmatically retrieve projects, keywords, and ranking data. This feature is available for users on the Agency Plan and above.
Authentication #
To use the API, you need your API Key.
- You can find your API Key in your TrueRanker account.
- Alternatively, if you use the WordPress plugin, it is located in the plugin menu section.
All requests must include the key parameter in the URL.
API Endpoints #
Base URL: https://app.trueranker.com/data
1. Get List of Projects #
Retrieves all projects associated with your account.
Request:
GET /project/list
Parameters:
| Parameter | Type | Required | Description |
key | String | Yes | Your API Key. |
Example:
Response Structure:
ok(boolean): Status of the request.data.projects: Array of project objects.id: Project identifier.name: Project name.domain: Project domain.type: Project type (1: Unique domain, 2: Domain+Subdomains, 3: Directory, 4: Unique URL, 5: Chrome Ext).num_keywords: Total keywords in the project.created_at: Creation date.
2. Get Keywords of a Project (Current Ranks) #
Retrieves all keywords for a specific project with their current ranking data.
Request:
GET /project/keyword/list
Parameters:
| Parameter | Type | Required | Description |
key | String | Yes | Your API Key. |
project | Integer | Yes | The Project ID (obtained from the project list). |
Example:
Response Structure:
data.keywords: Array of keyword objects.id: Keyword identifier.keyword: The actual term being tracked.location: City, province, or country tracked.country: Country code (e.g., ES, US).device: Device type (desktop/mobile).rank: Current rank.previous_rank: Rank from the previous check.best_rank_ever: Best position historically held.url: The specific URL that is ranking.volume: Monthly search volume.cpc: Cost Per Click.date: Date of the last update.
3. Get Keywords & Ranks by Date Range #
Retrieves keyword data and their ranking history between two specific dates.
Request:
GET /project/keyword/list (with date parameters)
Parameters:
| Parameter | Type | Required | Description |
key | String | Yes | Your API Key. |
project | Integer | Yes | The Project ID. |
start | Date | Yes | Start date in YYYYMMDD format. |
end | Date | Yes | End date in YYYYMMDD format. |
Example:
Response:
Returns the keyword data (same as above) plus an array/object containing the daily positions and URLs for the specified date range.
4. Get Keyword History (Single Keyword) #
Retrieves the detailed position history for a single specific keyword.
Request:
GET /project/keyword/get
Parameters:
| Parameter | Type | Required | Description |
key | String | Yes | Your API Key. |
keyword | Integer | Yes | The Keyword ID (obtained from the keyword list). |
days | Integer | No | Number of days to retrieve. If empty, returns the last 7 days. |
Example:
Response Structure:
data.keyword: Basic information about the keyword (id, term, location, device).data.history: Array of daily data points.date: Date of the record.rank: Position on that day.url: Ranking URL.cannibalization: Array of URLs and positions if multiple pages are competing for this keyword.
Error Handling #
All requests return a JSON object. Check the ok boolean field.
- If
ok: true, the request was successful. - If
ok: false, check theerrorfield for a description of the problem (e.g., “Invalid API Key”, “Project not found”).