Client Web Property Rank Report

GET URL

GET v3/{accountId}/web-properties/{webPropertyId}/rank-sources/{rankSourceId}/tp/{timePeriodId}/serp-items?reportingDuration={reportingDuration}&limit={limit}

Description

This endpoint provides a report of each result on a particular rank source that appeared for keywords tracked in a web property. The combination of search engine provider, location, and language are considered a single "rank source". For example, the following are four different rank sources:

  • Google (US / English)
  • Google (US / Spanish)
  • Google (Canada / English)
  • Google (Canada / French)

Each such report covers a single reporting time period at a weekly or daily frequency.

For some of the largest accounts that Conductor supports, clients should be prepared to digest reports up to 15MB gzip compressed with hundreds of thousands of search result items in them. Users may wish to process this report in a streaming fashion for import into their data warehouse if memory constraints are a consideration. Alternatively, you can limit the number of responses using the optional limit parameter documented below.

The items Conductor includes in this report are:

  • Top Rankers: The top 10 results for any keyword, regardless of whether they belong to a tracked web property or a tracked comparison web property.
  • Ranking results: Results that belong to a tracked web property.
  • Ranking comparison results: Results that belong to a comparison web property configured for the web property and rank source requested.
  • Results type: Results that are of a "universal" type—typically rich results such as image results or answer boxes.

It is possible for an item to satisfy more than one of these reasons for inclusion. For example, an item with CLASSIC_RANK of 2 pointing at a web property would have two different reasons to be included in this report since it's both a top ranker and targeted at a web property.

Update July 2022:

If your organization tracks any keywords at a daily frequency. The optional reportingDuration parameter set to DAY returns daily data. By default, the reportingDuration parameter is set to WEEK. You can change this to daily data by changing the reportingDuration parameter to DAY. See more information about configuring this parameter below.

The response is JSON of the following form:

[{
    serpItemObject,
    serpItemObject,
    serpItemObject,
    ...
    serpItemObject
}]

Where each "searchItemObject" has the following form:

[{
    "trackedSearchId": number,
    "webPropertyId": number,
    "targetDomainName": string,
    "itemType": string,
    "target": string|null,
    "targetUrl": string
    "ranks": {
        "UNIVERSAL_RANK": number|null,
        "TRUE_RANK": number|null,
        "CLASSIC_RANK": number|null
    },
}]

Parameters

accountId

The numeric identifier of a Conductor account. You can find this after logging into a Conductor account in the URL. Just go to Insight Stream: the numerical string in the URL represents the Account ID. For example:

https://app.conductor.com/5197/insight-stream

Required?: Yes
Type: String

webPropertyId

A web property’s numeric identifier string. This appears in the webPropertyId column of the Client Web Property Rank Report and appears in Conductor platform URLs that are specific to web properties. For example, in Explorer, the second numeric string represents the web property ID:

https://app.conductor.com/5197/web-properties/15350/rank-sources/1/explorer

Required?: Yes
Type: String

rankSourceId

The numeric identifier for the rank source.

This value also appears in the Rank Source List endpoint.

Required?: Yes
Type: String

timePeriodId

The timePeriodId determines the reporting time period in the Conductor platform associated with the data being called. How you configure this parameter depends on the setting in the reportingDuration parameter described below:

If the reportingDuration parameter is set to WEEK or null, time period IDs can be inferred from URLs in the Conductor platform. For example, in the example URL below for the Keywords report, the report indicates that the time periods 686 and 687 are being compared. New time periods always take the next subsequent integer from the current time period (i.e. time period 687 is followed by time period 688, 688 by 689, and so on). 

https://app.conductor.com/5197/keywords?rankType=TRUE_RANK&compareTP=686&reportTP=687&...

If the reportingDuration parameter is set to DAY, the timePeriodId parameter should be set to the specific date for which you are calling data, formatted as YYYYMMDD instead of the format described above.

Note that No daily data will be returned through API for requests using daily time periods more distant that 32 days from the current date. Conductor retains only 32 days of daily data.

Required?: Yes
Type: String

reportingDuration

This parameter determines whether the data called reflects the weekly data collect by Conductor or the daily data. Note that only organizations that track daily data in Conducotor will see results called through the API when it is set to DAY. By default, this parameter is set to WEEK.

Note that when this parameter is set to DAY, the timePeriodId parameter should be formatted as YYYYMMDD. 

Note also that no daily data will be returned through API for requests using daily time periods more distant that 32 days from the current date. Conductor retains only 32 days of daily data.

Required?: No (When left null, this parameter is set to WEEK)
Type: String

limit

The limit parameter limits the number of results that are returned if you are concerned about the size of your calls. Note that, depending on the configuration of the account, this response may be quite large.

Required?: No
Type: Integer

Reponse

trackedSearchId

The tracked keyword’s identifier string, which also appears in the Tracked Searches endpoint

webPropertyId

The web property’s numeric identifier string. This also appears in the webPropertyId column of the Web Property List endpoint and appears in Conductor platform URLs that are specific to web properties. For example, in Explorer, the second numeric string represents the web property ID:

https://app.conductor.com/5197/web-properties/15350/rank-sources/1/explorer

targetDomainName

The root domain associated with the targetURL, when targetURL is present

itemType

A string that represents Conductor's classification of that particular result type. This might be a standard blue link ("STANDARD_LINK") or a universal result of one type or another (such as "IMAGE_RESULT" or "VIDEO_RESULT"). 

target

The text of the "blue link" for this result snippet—usually the HTML title tag (when not rewritten by the search engine). For non-universal results with no target text, this will be blank.

targetUrl

The URL that is associated with this result, when present

ranks

An array of objects representing the various rank data associated with this client's tracked keyword:

  • TRUE_RANK: A number representing Conductor's True Rank for the result. True Rank is inclusive of standard link itemTypes and universal result itemTypes.
  • UNIVERSAL_RANK: A number representing the rank within the set of results belonging to a particular result type. For example, if four IMAGE_RESULT itemTypes are returned, the UNIVERSAL_RANK will indicate ranks one through four of each image result on the search engine results page. This also applies to STANDARD_LINK result types.
  • CLASSIC_RANK: A number representing Conductor's Standard Rank (formerly called Classic Rank) for the result. CLASSIC_RANK (Standard Rank) excludes universal itemTypes; it includes "just the classic blue links".

 

Try this endpoint with the interactive documentation

version 38 as of 2 months ago by Patrick Morgan