Skip to main content
POST
/
data-api
/
v1
/
async
/
highest_ranking_url_per_keyword
Query Highest Ranking URLs per Keyword (Async)
curl --request POST \
  --url 'https://api-universal.conductor.com/data-api/v1/async/highest_ranking_url_per_keyword?apiKey=&sig=' \
  --header 'Content-Type: application/json' \
  --header 'X-API-GATEWAY-KEY: <api-key>' \
  --data '
{
  "account_id": 101,
  "start_date": "2025-01-01",
  "end_date": "2025-03-03",
  "collection_frequency": "DAILY",
  "result_types": [
    "STANDARD_LINK"
  ],
  "domains": [
    "conductor.com",
    "seo.com"
  ],
  "includeMsv": true,
  "keyword_group_ids": [
    1,
    204,
    13
  ],
  "keyword_group_names": [
    "Brand",
    "Non-Brand",
    "Category"
  ],
  "web_property_ids": [
    122556,
    987654
  ],
  "rank_source_ids": [
    101,
    205,
    333
  ],
  "devices": [
    "DESKTOP",
    "SMARTPHONE"
  ],
  "locodes": [
    "US",
    "CA",
    "US NYC",
    "US-TX"
  ],
  "countries": [
    "US",
    "CA"
  ],
  "languages": [
    "en",
    "zh-Hans"
  ]
}
'
{
  "results": [
    [
      "123",
      "Example Account",
      "DF3DAF2955754FDDB180CF505AE4761E",
      "Example Organization",
      "456",
      "conductor.com",
      "2025-01-01",
      "2025-01-07",
      "2025-01-05",
      "GOOGLE_EN_US",
      "GOOGLE",
      "US",
      "en",
      "US",
      "DESKTOP",
      "best smartphones 2025",
      "Best Smartphones 2025 - Complete Guide",
      "https://example.com/best-smartphones-2025",
      "example.com",
      "www.example.com",
      "STANDARD_LINK",
      "1",
      "1",
      "1",
      "12,45,78",
      "Brand,Non-Brand,Category",
      "12000",
      "1.25",
      "0.75",
      "10000",
      "202506"
    ]
  ],
  "schema": [
    {
      "name": "account_id",
      "type": "integer"
    },
    {
      "name": "account_name",
      "type": "string"
    },
    {
      "name": "organization_id",
      "type": "string"
    },
    {
      "name": "organization_name",
      "type": "string"
    },
    {
      "name": "web_property_id",
      "type": "integer"
    },
    {
      "name": "web_property_name",
      "type": "string"
    },
    {
      "name": "time_period_start",
      "type": "date"
    },
    {
      "name": "time_period_end",
      "type": "date"
    },
    {
      "name": "collection_date",
      "type": "date"
    },
    {
      "name": "search_engine_name",
      "type": "string"
    },
    {
      "name": "search_engine",
      "type": "string"
    },
    {
      "name": "search_engine_country_code",
      "type": "string"
    },
    {
      "name": "search_engine_language_code",
      "type": "string"
    },
    {
      "name": "locode",
      "type": "string"
    },
    {
      "name": "device",
      "type": "string"
    },
    {
      "name": "query",
      "type": "string"
    },
    {
      "name": "title",
      "type": "string"
    },
    {
      "name": "normalized_url",
      "type": "string"
    },
    {
      "name": "root_domain",
      "type": "string"
    },
    {
      "name": "subdomain",
      "type": "string"
    },
    {
      "name": "result_type",
      "type": "string"
    },
    {
      "name": "rank_standard",
      "type": "integer"
    },
    {
      "name": "rank_true",
      "type": "integer"
    },
    {
      "name": "rank_result_type",
      "type": "integer"
    },
    {
      "name": "keyword_group_ids",
      "type": "string"
    },
    {
      "name": "keyword_group_names",
      "type": "string"
    },
    {
      "name": "average_search_volume",
      "type": "integer"
    },
    {
      "name": "cpc",
      "type": "float"
    },
    {
      "name": "competition",
      "type": "float"
    },
    {
      "name": "approximate_search_volume",
      "type": "integer"
    },
    {
      "name": "msv_month",
      "type": "integer"
    }
  ],
  "executionState": "COMPLETED",
  "executionId": "ath:abc123",
  "requestId": "req-123",
  "nextPageId": "87QUIJAKFQ9UIRJklafkg8wyuijFIAOqwfL9UIQOr==",
  "totalRowCount": 1000
}

Authorizations

​
apiKey
string
query
required

API Key as a query parameter

​
sig
string
query
required

Request signature computed using API key and secret. Valid for 5 minutes after creation.

​
X-API-GATEWAY-KEY
string
header
required

API Key as an HTTP header (must match apiKey query parameter)

Body

application/json

Submit a new query with filters and parameters. Returns an executionId to track the query.

​
account_id
integer
required

Required account ID to filter results.

Required range: x >= 1
Example:

101

​
start_date
string<date>
required

Start date of the time period (yyyy-MM-dd). If collection_frequency is WEEKLY or not set, this must be a Sunday. Maximum date range is 92 days.

Example:

"2025-01-01"

​
end_date
string<date>
required

End date of the time period (yyyy-MM-dd). If collection_frequency is WEEKLY or not set, this must be a Saturday.

Example:

"2025-03-03"

​
collection_frequency
enum<string>
default:WEEKLY

Frequency of data collection.

Available options:
DAILY,
WEEKLY
Example:

"DAILY"

​
result_types
string[]

(Optional) list of types of search results to include (e.g., STANDARD_LINK).

Example:
["STANDARD_LINK"]
​
domains
string[]

(Optional) list of domains to filter SERP items by.

Example:
["conductor.com", "seo.com"]
​
includeMsv
boolean
default:false

(Optional) Whether to include MSV (Monthly Search Volume) data.

Example:

true

​
keyword_group_ids
integer[]

(Optional) list of keyword group IDs to filter results. If provided, this takes priority over keyword_group_names.

Required range: x >= 1
Example:
[1, 204, 13]
​
keyword_group_names
string[]

(Optional) list of keyword group names to filter results. Used only if keyword_group_ids is empty.

Example:
["Brand", "Non-Brand", "Category"]
​
web_property_ids
integer[]

(Optional) list of web property IDs to filter results.

Required range: x >= 1
Example:
[122556, 987654]
​
rank_source_ids
integer[]

(Optional) list of rank source IDs to filter results.

Required range: x >= 1
Example:
[101, 205, 333]
​
devices
enum<string>[]

(Optional) list of device types to filter (case-insensitive).

Available options:
DESKTOP,
SMARTPHONE,
TABLET
Example:
["DESKTOP", "SMARTPHONE"]
​
locodes
string[]

(Optional) list of locodes to filter (case-insensitive). Based on ISO names from a predefined dictionary. A locode can represent a country ("US"), city ("US NYC"), state ("PL-02"), or a specific location (e.g., an airport).

Required string length: 2 - 12
Example:
["US", "CA", "US NYC", "US-TX"]
​
countries
string[]

(Optional) list of search engine country codes to filter (case-insensitive).

Required string length: 2
Example:
["US", "CA"]
​
languages
string[]

(Optional) list of search engine language codes to filter (case-insensitive; e.g., en, zh-Hans).

Required string length: 2 - 7
Example:
["en", "zh-Hans"]

Response

Query completed successfully (returned when polling with queryExecutionId)

​
results
string[][]

List of query results. Each item is a positional tuple row. Available only when executionState is COMPLETED.

Positional tuple row for highest ranking URL per keyword results. Column order matches the schema metadata. All values are returned as strings.

Required array length: 26 - 31 elements
​
executionState
enum<string>

Current execution state of the query:

  • IN_PROGRESS: The query is still running. Poll again later.
  • COMPLETED: The query finished successfully. Results are available.
  • FAILED: The query failed. Check the error message if available.
Available options:
IN_PROGRESS,
COMPLETED,
FAILED
​
executionId
string

Unique identifier for the query execution. Valid for 7 days. Use this for polling and pagination.

​
requestId
string

Unique identifier for the HTTP request, useful for support and debugging.

​
nextPageId
string

Token for retrieving the next page of results. Available as long as the executionId is valid (7 days). If null, there are no more pages available.

​
totalRowCount
integer<int64>

Total number of rows across all pages (if available).

​
schema
object[]

Column metadata providing the name and type for each position in the results tuple.