GetTopics

Status

Command status: Active
Supported by OpenApps API: Yes
Supported by Internal/Reseller API: Yes
Possibly queued processing: No

Purpose

This command returns Topical Trust Flow data.

Resources consumed

Resource Description

AnalysisResUnits

1000

RetrievalResUnits

Number of returned rows of data.

Parameters

Parameter Description

cmd

Required: must be set to: GetTopics

datasource

Optional - defaults to historic
Either: "fresh" - to query against Fresh Index, or "historic" - to query against Historic Index.

Item

Required: query string that one of the following:

  1. Root domain such as: example.com
  2. Sub domain such as: www.example.com
  3. URL such as: http://www.example.com - in this case only this specific URL will be checked

Count

Optional: maximum number of rows to be returned.

Default: 100
Max: All topics (actual number may change check TotalResults)

From

Optional: row number to start returning data from for pagnation.

Default: 1
Max: TotalResults

SortBy

Optional:

  • trust&flowlinks - (default) by Topical Trust Flow descending and then by links descending. The & will need encoding
  • topic - by topic (text)
  • links - by links
  • pages - by pages
  • refdomains - by refdomains
  • linksfromrefdomains - by links from ref domains

SortOrder

Optional:

  • asc - ascending
  • desc - (default) descending

UsePrefixScan

This parameter indicates that you would like links to any page under the specified prefix

eg setting
item=http://www.site.com/folder/
and
UsePrefixScan=1
will return any links to any page on www.site.com under /folder/

Default: 0

Examples queries and response

This query in the Fresh Index produces the following XML:

<?xml version="1.0" encoding="UTF-8"?>
<Result Code="OK" ErrorMessage="" FullError="">
   <GlobalVars ChargedAnalysisResUnits="1000" ChargedRetrievalResUnits="10" Cmd="GetTopics" IndexBuildDate="2017-10-17 20:51:37" IndexType="1" RemainingAnalysisResUnits="97092851" RemainingRetrievalResUnits="19462890" ServerBuild="2017-10-13 13:57:22" ServerName="ECHOLIMA" ServerVersion="1.0.6495.23321" UniqueIndexID="20171017205137-FRESH" />
   <DataTables Count="1">
      <DataTable Name="Topics" RowsCount="10" Headers="Topic|Links|TopicalTrustFlow|LinksFromRefDomains|RefDomains|Pages" Count="10" From="0" SortBy="topicaltrustflow&amp;links" SortOrder="desc" TotalResults="629">
         <Row>Regional/Europe|19008|41|1389300|2988|17508</Row>
         <Row>Computers/Internet/Web Design and Development|56189|40|2211973|3908|19177</Row>
         <Row>Shopping/Antiques and Collectibles|127|40|549237|78|6436</Row>
         <Row>Reference/Museums|401|39|557291|275|6207</Row>
         <Row>Reference/Education|15019|38|1178955|1885|11149</Row>
         <Row>Computers/Computer Science/Distributed Computing|326|36|85047|48|13331</Row>
         <Row>Computers/Internet|4993|33|1483738|1774|2106</Row>
         <Row>Business/Marketing and Advertising|9469|32|1421307|1781|9890</Row>
         <Row>Shopping/Entertainment|169|32|274453|73|10005</Row>
         <Row>Business|7600|31|992515|3346|2414</Row>
      </DataTable>
   </DataTables>
</Result>

JSON response

{
  "Code": "OK",
  "ErrorMessage": "",
  "FullError": "",
  "ChargedAnalysisResUnits": 1000,
  "ChargedRetrievalResUnits": 10,
  "Cmd": "GetTopics",
  "IndexBuildDate": "2017-10-17 20:51:37",
  "IndexType": 1,
  "RemainingAnalysisResUnits": 97090851,
  "RemainingRetrievalResUnits": 19462870,
  "ServerBuild": "2017-10-13 13:57:22",
  "ServerName": "ECHOLIMA",
  "ServerVersion": "1.0.6495.23321",
  "UniqueIndexID": "20171017205137-FRESH",
  "DataTables": {
    "Topics": {
      "Headers": {
        "Count": 10,
        "From": 0,
        "SortBy": "topicaltrustflow&links",
        "SortOrder": "desc",
        "TotalResults": 629
      },
      "Data": [
        {
          "Topic": "Regional/Europe",
          "Links": 19008,
          "TopicalTrustFlow": 41,
          "LinksFromRefDomains": 1389300,
          "RefDomains": 2988,
          "Pages": 17508
        },
        {
          "Topic": "Computers/Internet/Web Design and Development",
          "Links": 56189,
          "TopicalTrustFlow": 40,
          "LinksFromRefDomains": 2211973,
          "RefDomains": 3908,
          "Pages": 19177
        },
        {
          "Topic": "Shopping/Antiques and Collectibles",
          "Links": 127,
          "TopicalTrustFlow": 40,
          "LinksFromRefDomains": 549237,
          "RefDomains": 78,
          "Pages": 6436
        },
        {
          "Topic": "Reference/Museums",
          "Links": 401,
          "TopicalTrustFlow": 39,
          "LinksFromRefDomains": 557291,
          "RefDomains": 275,
          "Pages": 6207
        },
        {
          "Topic": "Reference/Education",
          "Links": 15019,
          "TopicalTrustFlow": 38,
          "LinksFromRefDomains": 1178955,
          "RefDomains": 1885,
          "Pages": 11149
        },
        {
          "Topic": "Computers/Computer Science/Distributed Computing",
          "Links": 326,
          "TopicalTrustFlow": 36,
          "LinksFromRefDomains": 85047,
          "RefDomains": 48,
          "Pages": 13331
        },
        {
          "Topic": "Computers/Internet",
          "Links": 4993,
          "TopicalTrustFlow": 33,
          "LinksFromRefDomains": 1483738,
          "RefDomains": 1774,
          "Pages": 2106
        },
        {
          "Topic": "Business/Marketing and Advertising",
          "Links": 9469,
          "TopicalTrustFlow": 32,
          "LinksFromRefDomains": 1421307,
          "RefDomains": 1781,
          "Pages": 9890
        },
        {
          "Topic": "Shopping/Entertainment",
          "Links": 169,
          "TopicalTrustFlow": 32,
          "LinksFromRefDomains": 274453,
          "RefDomains": 73,
          "Pages": 10005
        },
        {
          "Topic": "Business",
          "Links": 7600,
          "TopicalTrustFlow": 31,
          "LinksFromRefDomains": 992515,
          "RefDomains": 3346,
          "Pages": 2414
        }
      ]
    }
  }
}

Returned values

Topics data table will have the following variables:

Returned value Description
Global variables
Code Code indicating if deleting a download succeeded.
ErrorMessage A message explaining the error. This will be blank if the code is "OK".
FullError A verbose explanation of the error.
IndexBuildDate Date/time on which the index was updated.
IndexType Indicates whether the index was Historic or Fresh.
ServerBuild Date/time on which the server was built.
ServerName Name of the server where the file was stored.
ServerVersion The version of the server when the file was deleted.
UniqueIndexID Unique identifier for the index storing the deleted item.
Topics Headers
Count Number of rows requested
From The first result which this command returns.
SortBy Requested Sort By Field
SortOrder Sort Order Requested
TotalResults Total number of results found in the index for this domain
Topics Data
Topic The Topic for which the following links have been found
Links Number of links which directly pass trust flow of this topic
TopicalTrustFlow A value indicating the amount of trust flow passed by these links
LinksFromRefDomains Links which come from a domain which has this topic associated with it
RefDomains A count of the topical domains that point to the site/domain/URL
Pages Number of pages on the target site/domain/URL which have this topic associated with them