All API requests must have the following base URL: /api/v2/{API_KEY}/

All standard API responses are formatted as either XML or JSON. XML responses are the default. For JSON responses, add format=json to the request URL query string.

In most cases, the object(s) returned by a particular endpoint will not contain any sub-collections for that object type. Rather, each object will include a RequestUrl value, which is a reference to another endpoint where any sub-data contained within that result can be retrieved in full. For example, each project returned by the /projects/list endpoint will contain a pre-generated RequestUrl where you can retrieve the sites within that project; each site returned by /sites/list will contain a RequestUrl value to retrieve that site’s keywords; and so on.

The default daily limit for API calls is 1,000 calls per day. The daily count resets every night at midnight UTC. If you would like to exceed the daily limit, just talk to us.

API calls

• Response codes The API will return an HTTP response code of 200 for all correct requests. These other response codes will indicate errors.
• Projects: List This request returns all projects saved under your account.
• Projects: Create This request creates a new project under your account.
• Projects: Update This request updates a project’s name.
• Projects: Delete This request deletes a project.
• Sites: All This request returns all sites saved under your account.
• Sites: List This request returns all sites saved under the specified project id.
• Sites: Ranking Distributions This request returns all ranking distribution records for Google for a site with the specified id.
• Sites: Create This request creates a new site under the specified project id. When a site is created, it is automatically placed within a folder called “api” within your chosen project.
• Sites: Update This request updates a site under the specified id.
• Sites: Delete This request deletes a site under the specified id.
• Tags: List This request returns all tags saved under the specified site.
• Tags: Ranking Distributions This request returns all ranking distribution records for Google for a tag with the specified id.
• Keywords: List This request returns all keywords saved under the specified site.
• Keywords: Create This request creates new keyword(s).
• Keywords: Delete This request deletes a keyword or multiple keywords with the specified id(s).
• Rankings: List This request returns all rankings archived for specified keyword and date range. Each response contains a maximum of 30 days.
• SERPs: Show This request returns the archived SERP for the specified search engine and date for a specified keyword.
• SoV: Sites This request returns the SoV score for each competitor domain that appears on the SERP for a specified site.
• SoV: Tags This request returns the SoV score for each competitor domain that appears on the SERP for a specified tag.
• Most Frequent Domains: Sites This request returns the competitor domains most frequently in the top 10 for the site specified for the engine specified.
• Most Frequent Domains: Tags This request returns the competitor domains most frequently in the top 10 for the tag specified for the engine specified.
• Subaccounts: List This request displays the user and API key information for all subaccounts for a given admin user.
• Billing These requests provide data as seen within your billing summary.

Note that some bulk job types are included as a part of STAT’s standard API, while others are part of our optional paid specialty API services. See Overview: STAT API for more info.

• Bulk Export Jobs: List This request returns all bulk jobs currently stored in the system.
• Bulk Export Jobs: Ranks This request creates a new bulk ranking job.
• Bulk Export Jobs: Status This request returns the status of the specified bulk job id.
• Bulk Export Jobs: Delete This request deletes the bulk job with the specified ID.
• Bulk Export Jobs: Site Ranking Distributions This request creates a new bulk site ranking distributions job.
• Bulk Export Jobs: Tag Ranking Distributions This request creates a new bulk tag ranking distributions job.
• Bulk: Google HTML SERP, SERP, Google Ads (Optional specialized service) This Bulk:List request returns bulk API archives currently stored in the system in XML and JSON formats.

Response codes

The following are other possible response codes that may be returned. Your API wrapper should anticipate these response codes and deal with them gracefully.

Return to the top

Projects: List

HTTP Method: GET

XML request URL:

/projects/list

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response resultsreturned="11" responsecode="200">
 <Result>
  <Id>1</Id>
  <Name>celebrity</Name>
  <TotalSites>3</TotalSites>
  <CreatedAt>2009-12-18</CreatedAt>
  <UpdatedAt>2009-12-18</UpdatedAt>
  <RequestUrl>/sites/list?project_id=1</RequestUrl>
 </Result>
 ...
</Response>

JSON request URL:

/projects/list?format=json

JSON typical response:

{
   "Response":{
      "resultsreturned":"11",
      "responsecode":"200",
      "Result":[
         {
            "Id":"1",
            "Name":"celebrity",
            "TotalSites":"3",
            "CreatedAt":"2009-12-18",
            "UpdatedAt":"2009-12-18",
            "RequestUrl":"/sites/list?project_id=1&format=json"
         },
         ...
      ]
   }
}

Return to the top

Projects: Create

HTTP Method: GET

XML request URL:

/projects/create?name={projectId}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
  <Id>17</Id>
  <Name>ABC</Name>
  <CreatedAt>2011-05-14</CreatedAt>
  <UpdatedAt>2011-05-14</UpdatedAt>
 </Result>
</Response>

JSON request URL:

/projects/create?name={projectId}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"17",
         "Name":"ABC",
         "CreatedAt":"2011-05-14",
         "UpdatedAt":"2011-05-14"
      }
   }
}

Return to the top

Projects: Update

HTTP Method: GET

XML request URL:

/projects/update?id={projectId}&name={name}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
  <Id>17</Id>
  <Name>DEF</Name>
  <CreatedAt>2011-05-14</CreatedAt>
  <UpdatedAt>2011-05-14</UpdatedAt>
 </Result>
</Response>

JSON request URL:

/projects/update?id={projectId}&name={name}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"17",
         "Name":"DEF",
         "CreatedAt":"2011-05-14",
         "UpdatedAt":"2011-05-14"
      }
   }
}

Return to the top

Projects: Delete

HTTP Method: GET

XML request URL:

/projects/delete?id={projectId}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
  <Id>17</Id>
 </Result>
</Response>

JSON request URL:

/projects/delete?id={projectId}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"17"
      }
   }
}

Return to the top

Sites: All

HTTP Method: GET

The nextpage value only appears if there is an additional page of results to show. Use the results parameter to control how many results are returned per page (max 5,000).

XML request URL:

/sites/all[?start={start}][&results={results}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200" totalresults=”100” resultsreturned="50" nextpage=”/sites/all?start=50”>
 <Result>
  <Id>1</Id>
  <ProjectId>13</ProjectId>
  <FolderId>22</FolderId>
  <FolderName>Blog</FolderName>
  <Title>tourismvancouver.com</Title>
  <Url>tourismvancouver.com</Url>
  <Synced>N/A</Synced>
  <TotalKeywords>63</TotalKeywords>
  <CreatedAt>2011-01-25</CreatedAt>
  <UpdatedAt>2011-01-25</UpdatedAt>
  <RequestUrl>/keywords/list?site_id=1</RequestUrl>
 </Result>
 <Result>
  <Id>2</Id>
  <ProjectId>13</ProjectId>
  <FolderId>N/A</FolderId>
  <FolderName>N/A</FolderName>
  <Title>perezhilton.com</Title>
  <Url>perezhilton.com</Url>
  <Synced>1</Synced>
  <TotalKeywords>63</TotalKeywords>
  <CreatedAt>2011-01-25</CreatedAt>
  <UpdatedAt>2011-01-25</UpdatedAt>
  <RequestUrl>/keywords/list?site_id=2</RequestUrl>
 </Result>
...
</Response>

JSON request URL:

/sites/all?[start={start}][&results={results}&]format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "totalresults":"100",
      "resultsreturned":"50",
      "nextpage":"/sites/all?start=50&format=json",
      "Result":[
         {
            "Id":"1",
            "ProjectId":"13",
            "FolderId":"22",
            "FolderName":"Blog",
            "Title":"tourismvancouver.com",
            "Url":"tourismvancouver.com",
            "Synced":"N/A",
            "TotalKeywords":"63",
            "CreatedAt":"2011-01-25",
            "UpdatedAt":"2011-01-25",
            "RequestUrl":"/keywords/list?site_id=1&format=json"
         },
         {
            "Id":"2",
            "ProjectId":"13",
            "FolderId":"N/A",
            "FolderName":"N/A",
            "Title":"perezhilton.com",
            "Url":"perezhilton.com",
            "Synced":"1",
            "TotalKeywords":"63",
            "CreatedAt":"2011-01-25",
            "UpdatedAt":"2011-01-25",
            "RequestUrl":"/keywords/list?site_id=2&format=json"
         },
         ...
      ]
   }
}

Return to the top

Sites: List

HTTP Method: GET

XML request URL:

/sites/list?project_id={projectId}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
  <Id>1</Id>
  <FolderId>22</FolderId>
  <FolderName>Blog</FolderName>
  <Title>tourismvancouver.com</Title>
  <Url>tourismvancouver.com</Url>
  <Synced>N/A</Synced>
  <TotalKeywords>63</TotalKeywords>
  <CreatedAt>2011-01-25</CreatedAt>
  <UpdatedAt>2011-01-25</UpdatedAt>
  <RequestUrl>/keywords/list?site_id=1</RequestUrl>
 </Result>
 <Result>
  <Id>2</Id>
  <FolderId>N/A</FolderId>
  <FolderName>N/A</FolderName>
  <Title>perezhilton.com</Title>
  <Url>perezhilton.com</Url>
  <Synced>1</Synced>
  <TotalKeywords>63</TotalKeywords>
  <CreatedAt>2011-01-25</CreatedAt>
  <UpdatedAt>2011-01-25</UpdatedAt>
  <RequestUrl>/keywords/list?site_id=2</RequestUrl>
 </Result>
...
</Response>

JSON request URL:

/sites/list?project_id={projectId}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":[
         {
            "Id":"1",
            "FolderId":"22",
            "FolderName":"Blog",
            "Title":"tourismvancouver.com",
            "Url":"tourismvancouver.com",
            "Synced":"N/A",
            "TotalKeywords":"63",
            "CreatedAt":"2011-01-25",
            "UpdatedAt":"2011-01-25",
            "RequestUrl":"/keywords/list?site_id=1&format=json"
         },
         {
            "Id":"2",
            "FolderId":"N/A",
            "FolderName":"N/A",
            "Title":"perezhilton.com",
            "Url":"perezhilton.com",
            "Synced":"1",
            "TotalKeywords":"63",
            "CreatedAt":"2011-01-25",
            "UpdatedAt":"2011-01-25",
            "RequestUrl":"/keywords/list?site_id=2&format=json"
         },
         ...
      ]
   }
}

Return to the top

Sites: Ranking Distributions

HTTP Method: GET

The maximum date range can be no greater than 31 days.

XML request URL:

/sites/ranking_distributions?id={siteId}&from_date={YYYY-MM-DD}&to_date={YYYY-MM-DD}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <RankDistribution date="2015-03-15">
  <Google>
   <One>3386</One>
   <Two>748</Two>
   <Three>721</Three>
   <Four>481</Four>
   <Five>313</Five>
   <SixToTen>705</SixToTen>
   <ElevenToTwenty>301</ElevenToTwenty>
   <TwentyOneToThirty>104</TwentyOneToThirty>
   <ThirtyOneToForty>57</ThirtyOneToForty>
   <FortyOneToFifty>37</FortyOneToFifty>
   <FiftyOneToHundred>124</FiftyOneToHundred>
   <NonRanking>247</NonRanking>
  </Google>
  <GoogleBaseRank>
   <One>3409</One>
   <Two>765</Two>
   <Three>717</Three>
   <Four>475</Four>
   <Five>321</Five>
   <SixToTen>676</SixToTen>
   <ElevenToTwenty>290</ElevenToTwenty>
   <TwentyOneToThirty>102</TwentyOneToThirty>
   <ThirtyOneToForty>53</ThirtyOneToForty>
   <FortyOneToFifty>36</FortyOneToFifty>
   <FiftyOneToHundred>125</FiftyOneToHundred>
   <NonRanking>255</NonRanking>
  </GoogleBaseRank>
 </RankDistribution>
 <RankDistribution date="2013-08-09">
 ...
 </RankDistribution>
 ...
</Response>

JSON request URL:

/sites/ranking_distributions?id={siteId}&from_date={YYYY-MM-DD}&to_date={YYYY-MM-DD}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "RankDistribution":[
         {
            "date":"2015-03-15",
            "Google":{
               "One":"3386",
               "Two":"748",
               "Three":"721",
               "Four":"481",
               "Five":"313",
               "SixToTen":"705",
               "ElevenToTwenty":"301",
               "TwentyOneToThirty":"104",
               "ThirtyOneToForty":"57",
               "FortyOneToFifty":"37",
               "FiftyOneToHundred":"124",
               "NonRanking":"247"
            },
            "GoogleBaseRank":{
               "One":"3409",
               "Two":"765",
               "Three":"717",
               "Four":"475",
               "Five":"321",
               "SixToTen":"676",
               "ElevenToTwenty":"290",
               "TwentyOneToThirty":"102",
               "ThirtyOneToForty":"53",
               "FortyOneToFifty":"36",
               "FiftyOneToHundred":"125",
               "NonRanking":"255"
            }
         },
         {
            "date":"2013-08-09",
         	...
         },
         ...
      ]
   }
}

Return to the top

Sites: Create

HTTP Method: GET

For more information on how the DropWWWPrefix and DropDirectories values work, go to Creating your first project and site.

XML request URL:

/sites/create?project_id={projectId}&url={url}[&drop_www_prefix={boolean}][&drop_directories={boolean}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
  <Id>146</Id>
  <ProjectId>13</ProjectId>
  <Title>google.com</Title>
  <Url>google.com</Url>
  <DropWWWPrefix>true</DropWWWPrefix>
  <DropDirectories>true</DropDirectories>
  <CreatedAt>2011-05-14</CreatedAt>
 </Result>
</Response>

JSON request URL:

/sites/create?project_id={projectId}&url={url}[&drop_www_prefix={boolean}][&drop_directories={boolean}]&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"146",
         "ProjectId":"13",
         "Title":"google.com",
         "Url":"google.com",
         "DropWWWPrefix":"true",
         "DropDirectories":"true",
         "CreatedAt":"2011-05-14"
      }
   }
}

Return to the top

Sites: Update

HTTP Method: GET

XML request URL:

/sites/update?id={siteId}[&url={url}][&title={title}][&drop_www_prefix={boolean}][&drop_directories={boolean}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
  <Id>146</Id>
  <ProjectId>13</ProjectId>
  <Title>my site</Title>
  <Url>google.com</Url>
  <DropWWWPrefix>true</DropWWWPrefix>
  <DropDirectories>true</DropDirectories>
  <CreatedAt>2011-05-14</CreatedAt>
  <UpdatedAt>2011-05-14</UpdatedAt>
 </Result>
</Response>

JSON request URL:

/sites/update?id={siteId}[&url={url}][&title={title}][&drop_www_prefix={boolean}][&drop_directories={boolean}]&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"146",
         "ProjectId":"13",
         "Title":"my site",
         "Url":"google.com",
         "DropWWWPrefix":"true",
         "DropDirectories":"true",
         "CreatedAt":"2011-05-14",
         "UpdatedAt":"2011-05-14"
      }
   }
}

Return to the top

Sites: Delete

HTTP Method: GET

XML request URL:

/sites/delete?id={siteId}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
  <Id>146</Id>
 </Result>
</Response>

JSON request URL:

/sites/delete?id={siteId}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"146"
      }
   }
}

Return to the top

Tags: List

Use the results parameter to control how many results are returned per-page (max 5,000).

HTTP Method: GET

XML request URL:

/tags/list?site_id={siteId}[&start={start}][&results={results}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200" resultsreturned="100" totalresults="223" nextpage="/tags/list?site_id=1&start=100">
 <Result>
 <Id>16900</Id>
 <Tag>abc</Tag>
 <Type>Standard</Type>
 <Keywords>
  <Id>4525</Id>
  <Id>4526</Id>
 </Keywords>
 </Result>
 <Result>
  <Id>16902</Id>
  <Tag>abcd</Tag>
  <Type>Dynamic</Type>
  <Keywords>none</Keywords>
 </Result>
 ...
</Response>

JSON request URL:

/tags/list?site_id={siteId}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "resultsreturned":"100",
      "totalresults":"223",
      "nextpage":"/tags/list?site_id=1&start=100&format=json",
      "Result":[
         {
            "Id":"16900",
            "Tag":"abc",
            "Type":"Standard",
            "Keywords":{
               "Id":[
                  "4525",
                  "4526"
               ]
            }
         },
         {
            "Id":"16902",
            "Tag":"abcd",
            "Type":"Dynamic",
            "Keywords":"none"
         }
      ]
   }
}

Return to the top

Tags: Ranking Distributions

The maximum date range can be no greater than 31 days.

XML request URL:

/tags/ranking_distributions?id={tagId}&from_date={YYYY-MM-DD}&to_date={YYYY-MM-DD}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <RankDistribution date="2015-03-15">
  <Google>
   <One>3386</One>
   <Two>748</Two>
   <Three>721</Three>
   <Four>481</Four>
   <Five>313</Five>
   <SixToTen>705</SixToTen>
   <ElevenToTwenty>301</ElevenToTwenty>
   <TwentyOneToThirty>104</TwentyOneToThirty>
   <ThirtyOneToForty>57</ThirtyOneToForty>
   <FortyOneToFifty>37</FortyOneToFifty>
   <FiftyOneToHundred>124</FiftyOneToHundred>
   <NonRanking>247</NonRanking>
  </Google>
  <GoogleBaseRank>
   <One>3409</One>
   <Two>765</Two>
   <Three>717</Three>
   <Four>475</Four>
   <Five>321</Five>
   <SixToTen>676</SixToTen>
   <ElevenToTwenty>290</ElevenToTwenty>
   <TwentyOneToThirty>102</TwentyOneToThirty>
   <ThirtyOneToForty>53</ThirtyOneToForty>
   <FortyOneToFifty>36</FortyOneToFifty>
   <FiftyOneToHundred>125</FiftyOneToHundred>
   <NonRanking>255</NonRanking>
  </GoogleBaseRank>
 </RankDistribution>

JSON request URL:

/tags/ranking_distributions?id={tagId}&from_date={YYYY-MM-DD}&to_date={YYYY-MM-DD}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "RankDistribution":[
         {
            "date":"2015-03-15",
            "Google":{
               "One":"3386",
               "Two":"748",
               "Three":"721",
               "Four":"481",
               "Five":"313",
               "SixToTen":"705",
               "ElevenToTwenty":"301",
               "TwentyOneToThirty":"104",
               "ThirtyOneToForty":"57",
               "FortyOneToFifty":"37",
               "FiftyOneToHundred":"124",
               "NonRanking":"247"
            },
            "GoogleBaseRank":{
               "One":"3409",
               "Two":"765",
               "Three":"717",
               "Four":"475",
               "Five":"321",
               "SixToTen":"676",
               "ElevenToTwenty":"290",
               "TwentyOneToThirty":"102",
               "ThirtyOneToForty":"53",
               "FortyOneToFifty":"36",
               "FiftyOneToHundred":"125",
               "NonRanking":"255"
            }
         },
         {
            "date":"2013-08-09",
            ...
         },
         ...
      ]
   }

Return to the top

Keywords: List

HTTP Method: GET

The nextpage= value contains the URL to retrieve the next page of results. Use the results parameter to control how many results are returned per-page (max 5,000).

XML request URL:

/keywords/list?site_id={siteId}[&start={start}][&results={results}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200" resultsreturned="63" totalresults=”150” nextpage="/keywords/list?site_id=1&start=1000">
 <Result>
  <Id>11</Id>
  <Keyword>black celebrity gossip</Keyword>
  <KeywordMarket>US-en</KeywordMarket>
  <KeywordLocation>Boston</KeywordLocation>
  <KeywordDevice>Smartphone</KeywordDevice>
  <KeywordTranslation>potins de célébrités noires</KeywordTranslation>
  <KeywordTags>gossip</KeywordTags>
  <KeywordStats>
   <AdvertiserCompetition>0.86748</AdvertiserCompetition>
   <GlobalSearchVolume>80000</GlobalSearchVolume>
   <RegionalSearchVolume>54000</RegionalSearchVolume>
   <LocalSearchTrendsByMonth>
    <Oct>-</Oct>
    <Sep>49500</Sep>
    <Aug>60500</Aug>
    <Jul>49500</Jul>
    <Jun>49500</Jun>
    <May>49500</May>
    <Apr>49500</Apr>
    <Mar>49500</Mar>
    <Feb>49500</Feb>
    <Jan>49500</Jan>
    <Dec>40500</Dec>
    <Nov>49500</Nov>
   </LocalSearchTrendsByMonth>
   <CPC>1.42</CPC>
  </KeywordStats>
  <KeywordRanking date="2014-07-09">
   <Google>
   <Rank>1</Rank>
   <BaseRank>1</BaseRank>
   <Url>www.zillow.com/mortgage-rates/ca/</Url>
   </Google>
  </KeywordRanking>
  <CreatedAt>2011-01-25</CreatedAt>
  <RequestUrl>/rankings?keyword_id=11&from_date=2011-01-25&to_date=</RequestUrl>
 </Result>
 ...
</Response>

JSON request URL:

/keywords/list?site_id={siteId}[&start={start}][&results={results}]&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "resultsreturned":"63",
      "totalresults":"150",
      "nextpage":"/keywords/list?site_id=1&start=1000&format=json",
      "Result":[
         {
            "Id":"11",
            "Keyword":"black celebrity gossip",
            "KeywordMarket":"US-en",
            "KeywordLocation":"Boston",
            "KeywordDevice":"Smartphone",
            "KeywordTranslation":"potins de célébrités noires",
            "KeywordTags":"gossip",
            "KeywordStats":{
               "AdvertiserCompetition":"0.86748",
               "GlobalSearchVolume":"80000",
               "RegionalSearchVolume":"54000",
               "LocalSearchTrendsByMonth":{
                  "Oct":"-",
                  "Sep":"49500",
                  "Aug":"60500",
                  "Jul":"49500",
                  "Jun":"49500",
                  "May":"49500",
                  "Apr":"49500",
                  "Mar":"49500",
                  "Feb":"49500",
                  "Jan":"49500",
                  "Dec":"40500",
                  "Nov":"49500"
               },
               "CPC":"1.42"
            },
            "KeywordRanking":{
               "date":"2014-07-09",
               "Google":{
                  "Rank":"1",
                  "BaseRank":"1",
                  "Url":"www.zillow.com/mortgage-rates/ca/"
               },
            },
            "CreatedAt":"2011-01-25",
            "RequestUrl":"/rankings?keyword_id=11&format=json&from_date=2011-01-25&to_date="
         },
         ...
      ]
   }
}

Return to the top

Keywords: Create

Multiple keywords can be separated by commas. You can create keywords that include commas by using a backslash to escape them. For example:

/keywords/create?site_id={siteId}&market=US-en&location=Boston&device=smartphone&keyword=shirt\,shoes

Without the backslash, the code creates two keyword search terms (“shirt” and “shoes”):

/keywords/create?site_id={siteId}&market=US-en&location=Boston&device=smartphone&keyword=shirt,shoes

Tags are optional.

HTTP Method: GET

XML request URL:

/keywords/create?site_id={siteId}&market={market}&keyword={keywords}[&location={location}][&device={device}][&tag={tags}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200" resultsreturned=”2”>
 <Result>
  <Id>3008</Id>
  <Keyword>shirt</Keyword>
  <KeywordMarket>US-en</KeywordMarket>
  <KeywordLocation>Boston</KeywordLocation>
  <KeywordDevice>Smartphone</KeywordDevice>
  <CreatedAt>2011-01-25</CreatedAt>
 </Result>
 <Result>
  <Id>3009</Id>
  <Keyword>shoes</Keyword>
  <KeywordMarket>US-en</KeywordMarket>
  <KeywordLocation>Boston</KeywordLocation>
  <KeywordDevice>Smartphone</KeywordDevice>
  <CreatedAt>2011-01-25</CreatedAt>
 </Result>
</Response>

JSON request URL:

/keywords/create?site_id={siteId}&market={market}&keyword={keywords}[&location={location}][&device={device}][&tag={tags}]&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "resultsreturned":"2",
      "Result":[
         {
            "Id":"3008",
            "Keyword":"shirt",
            "KeywordMarket":"US-en",
            "KeywordLocation":"Boston",
            "KeywordDevice":"Smartphone",
            "CreatedAt":"2011-01-25"
         },
         {
            "Id":"3009",
            "Keyword":"shoes",
            "KeywordMarket":"US-en",
            "KeywordLocation":"Boston",
            "CreatedAt":"2011-01-25"
         }
      ]
   }
}

Return to the top

Keywords: Delete

When you delete a keyword, all of the historical ranking data for that keyword is permanently erased from your account. If you want to keep the data, you can turn tracking off for a keyword instead. You can delete multiple keywords using comma separated values for id.

HTTP Method: GET

XML request URL:

/keywords/delete?id={keywordId}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
  <Id>3008</Id>
 </Result>
</Response>

JSON request URL:

/keywords/delete?id={keywordId}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"3008"
      }
   }
}

Return to the top

Rankings: List

HTTP Method: GET

The nextpage= value contains the URL to retrieve the next page of results. Each result is separated into three sub-results, one for each search engine.

XML request URL:

/rankings/list?keyword_id={keywordId}[&from_date={YYYY-MM-DD}][&to_date={YYYY-MM-DD}][&start={start}][&results={results}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200" resultsreturned="30" totalresults=”1000” nextpage="/rankings/list?keyword_id=14&from_date=2011-01-25&to_date=2011-03-13&start=60">
 <Result date="2011-01-25">
  <Google>
   <Rank>55</Rank>
   <Url>http://tourismvancouver.com/5014342/nobody-cares-about-perez-hilton</Url>
   <BaseRank>50</BaseRank>
   <RequestUrl>/serps/show?keyword_id=14&engine=google&date=2011-01-25</RequestUrl>
  </Google>
 </Result>
 ...
</Response>

JSON request URL:

/rankings/list?keyword_id={keywordId}[&from_date={YYYY-MM-DD}][&to_date={YYYY-MM-DD}][&start={start}][&results={results}]&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "resultsreturned":"30",
      "totalresults":"1000",
      "nextpage":"/rankings/list?keyword_id=14&from_date=2011-01-25&to_date=2011-03-13&start=60&format=json",
      "Result":[
         {
            "date":"2011-01-25",
            "Google":{
               "Rank":"55",
               "Url":"http://tourismvancouver.com/5014342/nobody-cares-about-perez-hilton",
               "BaseRank":"50",
               "RequestUrl":"/serps/show?keyword_id=14&engine=google&date=2011-01-25&format=json"
            }
         },
         {
            "date":"2011-01-26",
            ...
         }
         ...
      ]
   }
}

Return to the top

SERPs: Show

HTTP Method: GET

XML request URL:

/serps/show?keyword_id={keywordId}&engine={engine}&date={YYYY-MM-DD}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
    <ResultTypes>
       <ResultType>news</ResultType>
       <ResultType>amp</ResultType>
       <ResultType>carousel</ResultType>
    </ResultTypes>
    <Rank>2</Rank>
    <BaseRank></BaseRank>
    <Url>
          www.slashgear.com
    </Url>
  <Title>Cat Backpacks</Title>
  <Protocol>https</Protocol>
  </Result>
  <Result>
    <ResultTypes>
       <ResultType>news</ResultType>
       <ResultType>amp</ResultType>
       <ResultType>carousel</ResultType>
    </ResultTypes>
    <Rank>2</Rank>
    <BaseRank></BaseRank>
    <Url>
          www.space.com
    </Url>
  <Title>Hamster Wheel</Title>
  <Protocol>https</Protocol>
  </Result>
...
</Response>

JSON request URL:

/serps/show?keyword_id={keywordId}&engine={engine}&date={YYYY-MM-DD}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":[
              {
                  "ResultTypes": {
                      "ResultType":[
                          "amp",
                          "carousel",
                          "news"
                       ]
                   },
                   "Rank":"2",
                   "BaseRank":"",
                   "Url":"www.slashgear.com",
                   "Title": "Cat Backpacks",
                   "Protocol":"https"
               },
              {
                  "ResultTypes": {
                      "ResultType":[
                          "amp",
                          "carousel",
                          "news"
                       ]
                   },
                   "Rank":"2",
                   "BaseRank":"",
                   "Url":"www.space.com",
                   "Title": "Hamster Wheel",
                   "Protocol":"https"
                }
         ]
  }
}

Return to the top

SoV: Sites

HTTP Method: GET

The score is calculated on each domain for all the keywords in the site specified. The response contains a date-wise breakdown of each competitor domain, the score, and whether or not it is a pinned site.

XML request URL:

/sites/sov?id={siteId}&from_date={YYYY-MM-DD}&to_date={YYYY-MM-DD}[&start={start}][&results={results}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200" resultsreturned="XX" totalresults="XXXX" nextpage="/[sites/tags]/sov?id=XX&from_date=XXXX-XX-XX&to_date=YYYY-YY-YY&start=XX">
<ShareOfVoice date="XXXX-XX-XX">
	<Site>
		<Domain>xxx.com</Domain>
		<Share>13.0</Share>
		<Pinned>false</Pinned>
	</Site>
	<Site>
		<Domain>yyy.com</Domain>
		<Share>9.0</Share>
		<Pinned>true</Pinned>
	</Site>
        ...

</ShareOfVoice>
<ShareOfVoice date="YYYY-YY-YY">
	<Site>
		<Domain>xxx.com</Domain>
		<Share>11.0</Share>
		<Pinned>false</Pinned>
	</Site>
	<Site>
		<Domain>yyy.com</Domain>
		<Share>10.0</Share>
		<Pinned>true</Pinned>
	</Site>
        ...

</ShareOfVoice>
    ...

JSON request URL:

/sites/sov?id={siteId}&from_date={YYYY-MM-DD}&to_date={YYYY-MM-DD}[&start={start}][&results={results}]&format=json

JSON typical response:

{
    "Response":{
        "responsecode":"200",
        "resultsreturned":"XX",
        "totalresults":"XXXX",
        "nextpage":"/[sites/tags]/sov?id=XX&from_date=XXXX-XX-XX&to_date=YYYY-YY-YY&start=XX",
        "ShareOfVoice":[
            {
                "date":"XXXX-XX-XX",
                "Site":[
                    {
                        "Domain":"xxx.com",
                        "Share":"13.0",
                        "Pinned":"false"
                    },
                    {
                        "Domain":"yyy.com",
                        "Share":"9.0",
                        "Pinned":"true"
                    }
                ]
            },
            {
                "date":"YYYY-YY-YY",
                "Site":[
                    {
                        "Domain":"xxx.com",
                        "Share":"11.0",
                        "Pinned":"false"
                    },
                    {
                        "Domain":"yyy.com",
                        "Share":"10.0",
                        "Pinned":"true"
                    }
                ]
            }
        ]
    }
}

Return to the top

SoV: Tags

The SoV score is calculated on each domain for all the keywords in the tag specified. The response con-tains a date-wise breakdown of each competitor domain, the score, and whether or not it a pinned site.

HTTP Method: GET

XML request URL:

/tags/sov?id={tagId}&from_date={YYYY-MM-DD}&to_date={YYYY-MM-DD}[&start={start}][&results={results}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200" resultsreturned="XX" totalresults="XXXX" nextpage="/tags/sov?id=XX&from_date=XXXX-XX-XX&to_date=YYYY-YY-YY&start=XX">
    <ShareOfVoice date="XXXX-XX-XX">
        <Site>
            <Domain>xxx.com</Domain>
            <Share>13.0</Share>
            <Pinned>false</Pinned>
        </Site>
        <Site>
            <Domain>yyy.com</Domain>
            <Share>9.0</Share>
            <Pinned>true</Pinned>
        </Site>
        ...
    </ShareOfVoice>
    <ShareOfVoice date="YYYY-YY-YY">
        <Site>
            <Domain>xxx.com</Domain>
            <Share>11.0</Share>
            <Pinned>false</Pinned>
        </Site>
        <Site>
            <Domain>yyy.com</Domain>
            <Share>10.0</Share>
            <Pinned>true</Pinned>
        </Site>
        ...
    </ShareOfVoice>
    ...
</Response>

JSON request URL:

/tags/sov?id={tagId}&from_date={YYYY-MM-DD}&to_date={YYYY-MM-DD}[&start={start}][&results={results}]&format=json

JSON typical response:

{
    "Response":{
        "responsecode":"200",
        "resultsreturned":"XX",
        "totalresults":"XXXX",
        "nextpage":"/tags/sov?id=XX&from_date=XXXX-XX-XX&to_date=YYYY-YY-YY&start=XX",
        "ShareOfVoice":[
            {
                "date":"XXXX-XX-XX",
                "Site":[
                    {
                        "Domain":"xxx.com",
                        "Share":"13.0",
                        "Pinned":"false"
                    },
                    {
                        "Domain":"yyy.com",
                        "Share":"9.0",
                        "Pinned":"true"
                    }
                ]
            },
            {
                "date":"YYYY-YY-YY",
                "Site":[
                    {
                        "Domain":"xxx.com",
                        "Share":"11.0",
                        "Pinned":"false"
                    },
                    {
                        "Domain":"yyy.com",
                        "Share":"10.0",
                        "Pinned":"true"
                    }
                ]
            }
        ]

Return to the top

Most Frequent Domains: Sites

STAT tallies which competitors are most frequently in the top 10 for the keyword set by engine and the percentage coverage for this set.

HTTP Method: GET

XML request URL:

/sites/most_frequent_domains?id={siteId}&engine={engine}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
    <Site>
        <Domain>xxx.com</Domain>
        <TopTenResults>800</TopTenResults>
        <ResultsAnalyzed>16800</ResultsAnalyzed>
        <Coverage>4.76%</Coverage>
        <AnalyzedOn>XXXX-XX-XX</AnalyzedOn>
    </Site>
    <Site>
        <Domain>yyy.com</Domain>
        <TopTenResults>686</TopTenResults>
        <ResultsAnalyzed>16800</ResultsAnalyzed>
        <Coverage>4.08</Coverage>
        <AnalyzedOn>XXXX-XX-XX</AnalyzedOn>
    </Site>
    ...
</Response>

JSON request URL:

/sites/most_frequent_domains?id={siteId}&engine={engine}&format=json

JSON typical response:

{
    "Response":{
        "responsecode":"200",
        "Site":[
            {
                "Domain":"xxx.com",
                "TopTenResults":"800",
                "ResultsAnalyzed":"16800",
                "Coverage":"4.76%",
                "AnalyzedOn":"XXXX-XX-XX"
            },
            {
                "Domain":"yyy.com",
                "TopTenResults":"686",
                "ResultsAnalyzed":"16800",
                "Coverage":"4.08",
                "AnalyzedOn":"XXXX-XX-XX"
            }
        ]
    }
}

Return to the top

Most Frequent Domains: Tags

STAT tallies which competitors are most frequently in the top 10 for the keyword set by engine and the percentage coverage for this set.

HTTP Method: GET

XML request URL:

/tags/most_frequent_domains?id={tagId}&engine={engine}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
    <Site>
        <Domain>xxx.com</Domain>
        <TopTenResults>800</TopTenResults>
        <ResultsAnalyzed>16800</ResultsAnalyzed>
        <Coverage>4.76%</Coverage>
        <AnalyzedOn>XXXX-XX-XX</AnalyzedOn>
    </Site>
    <Site>
        <Domain>yyy.com</Domain>
        <TopTenResults>686</TopTenResults>
        <ResultsAnalyzed>16800</ResultsAnalyzed>
        <Coverage>4.08</Coverage>
        <AnalyzedOn>XXXX-XX-XX</AnalyzedOn>
    </Site>
    ...
</Response>

JSON request URL:

/tags/most_frequent_domains?id={tagId}&engine={engine}&format=json

JSON typical response:

{
    "Response":{
        "responsecode":"200",
        "Site":[
            {
                "Domain":"xxx.com",
                "TopTenResults":"800",
                "ResultsAnalyzed":"16800",
                "Coverage":"4.76%",
                "AnalyzedOn":"XXXX-XX-XX"
            },
            {
                "Domain":"yyy.com",
                "TopTenResults":"686",
                "ResultsAnalyzed":"16800",
                "Coverage":"4.08",
                "AnalyzedOn":"XXXX-XX-XX"
            }
        ]
    }
}

Return to the top

Subaccounts: List

HTTP Method: GET

XML request URL:

/subaccounts/list

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <User>
  <Id>3008</Id>
  <Login>user3008</Login>
  <ApiKey>540D245230F1638E3F6542F465232534</ApiKey>
  <CreatedAt>2011-01-25</CreatedAt>
 </User>
  ...
 <User>
  <Id>3009</Id>
  <Login>user3009</Login>
  <ApiKey>697D211110F1611A3F7657F460987222</ApiKey>
  <CreatedAt>2011-01-26</CreatedAt>
 <User>
<Response>

JSON request URL:

/subaccounts/list?format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "User":[
        {
            "Id":"3008",
            "Login":"user3008",
            "ApiKey":"540D245230F1638E3F6542F465232534",
            "CreatedAt":"2011-01-25"
         },
         {
            "Id":"3009",
            "Login":"user3009",
            "ApiKey":"697D211110F1611A3F7657F460987222",
            "CreatedAt":"2011-01-26"
         }
      ]
   }
}

Return to the top

Billing

There are three Billing API requests available:

• Billing: Bill This request provides the data seen on the Bill tab of the billing summary. It includes keyword tracking, optional services and totals.
• Billing: User breakdown This request provides the data seen on the User Breakdown tab of the billing summary. It includes tracked keywords by user, percentage of bill by user and total by user.
• Billing: Site breakdown This request provides the data seen on the Site Breakdown tab of the billing summary. It includes tracked keywords, percentage of bill and site total with site info.

For the most up-to-date Billing API information, please contact our support team: support@getSTAT.com

Return to the top

Bulk Export Jobs: List

The Bulk List API returns data in a paginated format. It always returns the first hundred results when no page is specified. To navigate to subsequent pages, the start parameter can be passed with values at increments of 100. For example, to get to page 2, pass start=100. For page 3, start=200, etc

XML request URL:

/bulk/list

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode=”200”>
 <Result>
  <Id>100</Id>
  <JobType>ranks</JobType>
  <Format>xml</Format>
  <Date>2011-02-05</Date>
  <Status>NotStarted</Status>
  <Url></Url>
  <StreamUrl></StreamUrl>
  <CreatedAt>2011-02-06</CreatedAt>
 </Result>
 <Result>
  <Id>99</Id>
  <JobType>ranks</JobType>
  <Format>json</Format>
  <Date>2014-02-04</Date>
  <Status>Completed</Status>
  <Url></Url>
  <StreamUrl></StreamUrl>
  <CreatedAt>2014-02-05</CreatedAt>
 </Result>
 ...
</Response>

JSON request URL:

/bulk/list?format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":[
         {
            "Id":"100",
            "JobType":"ranks",
            "Format":"xml",
            "Date":"2011-02-05",
            "Status":"NotStarted",
            "Url":null,
            "StreamUrl":null,
            "CreatedAt":"2011-02-06"
         },
         {
            "Id":"99",
            "JobType":"ranks",
            "Format":"json",
            "Date":"2014-02-04",
            "Status":"Completed",
            "Url":null,
            "StreamUrl":null,
            "CreatedAt":"2014-02-05"
         },
         ...
      ]
   }
}

Return to the top

Bulk Export Jobs: Ranks

If no site_id is passed in, ranks are reported for all sites in the system on the given date. (Note that you cannot create bulk jobs for the current date or dates in the future.) Optionally, pass in one or more site_id values (comma separated) to report on specific sites.

rank_type: This parameter changes the call between getting the highest ranks for the keywords for the date with the value highest, or getting all the ranks for each engine for a keyword for a date with the value all. Defaults to highest if not provided.

engines: This parameter lets you choose which search engines to include in the export, defaulting to Google. Engines can be passed in comma separated to get multiple.

currently_tracked_only: This parameter will cause the API to output only keywords which currently have tracking on at the time the API request is generated.

crawled_keywords_only: This parameter causes the API to only include output for keywords that were crawled on the date parameter provided.

HTTP Method: GET

XML request URL:

/bulk/ranks?date={YYYY-MM-DD}[&site_id={siteIds}][&rank_type={ranktype}][&engines={engines}][&currently_tracked_only={boolean}][&crawled_keywords_only={boolean}]

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode=”200”>
 <Result>
  <Id>1</Id>
 </Result>
</Response>

JSON request URL:

/bulk/ranks?date={YYYY-MM-DD}[&site_id={siteIds}][&rank_type={ranktype}][&engines={engines}][&currently_tracked_only={boolean}][&crawled_keywords_only={boolean}]&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"1"
      }
   }
}

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
<Project>
  <Id>9</Id>
  <Name>STAT Search Analytics</Name>
  <TotalSites>4</TotalSites>
  <CreatedAt>2014-11-13</CreatedAt>
  <Site>
    <Id>19</Id>
    <Url>getstat.com</Url>
    <TotalKeywords>1203</TotalKeywords>
    <CreatedAt>2014-11-13</CreatedAt>
      <Keyword>
        <Id>154010</Id>
        <Keyword>unlimited tracking</Keyword>
        <KeywordMarket>US-en</KeywordMarket>
        <KeywordLocation />
        <KeywordDevice>desktop</KeywordDevice>
        <KeywordTranslation>hello</KeywordTranslation>
        <KeywordCategories />
        <KeywordTags />
        <KeywordStats>
          <AdvertiserCompetition>0.04</AdvertiserCompetition>
          <GlobalSearchVolume>40500</GlobalSearchVolume>
          <TargetedSearchVolume>27100</TargetedSearchVolume>
          <LocalSearchTrendsByMonth>
            <Apr>40500</Apr>
            <Mar>33100</Mar>
            <Feb>27100</Feb>
            <Jan>27100</Jan>
            <Dec>27100</Dec>
            <Nov>27100</Nov>
            <Oct>27100</Oct>
            <Sep>27100</Sep>
            <Aug>27100</Aug>
            <Jul>27100</Jul>
            <Jun>27100</Jun>
            <May>27100</May>
          </LocalSearchTrendsByMonth>
          <CPC>0.24</CPC>
        </KeywordStats>
        <CreatedAt>2014-11-13</CreatedAt>
        <Ranking date="2015-05-12" type=“highest”>
          <Google>
            <Rank>6</Rank>
            <BaseRank>6</BaseRank>
            <Url>getstat.com/take-the-tour</Url>
          </Google>
          <Bing>
            <Rank>29</Rank>
            <Url>getstat.com/take-the-tour</Url>
          </Bing>
        </Ranking>
      </Keyword>
      <Keyword>
       ...
      </Keyword>
       ...
    </Site>
  </Project>
</Response>

{
   "Response":{
       "responsecode":"200",
       "Project":{
           "Id":"9",
           "Name":"STAT Search Analytics",
           "TotalSites":"4",
           "CreatedAt":"2014-11-13",
           "Site":{
               "Id":"19",
               "Url":"getstat.com",
               "TotalKeywords":"1203",
               "CreatedAt":"2014-11-13",
               "Keyword":[
                   {
                       "Id":"154010",
                       "Keyword":"unlimited tracking",
                       "KeywordMarket":"US-en",
                       "KeywordLocation":null,
                       "KeywordDevice":"desktop",
                       "KeywordTranslation":"hello",
                       "KeywordCategories":null,
                       "KeywordTags":null,
                       "KeywordStats":{
                           "AdvertiserCompetition":"0.04",
                           "GlobalSearchVolume":"40500",
                           "TargetedSearchVolume":"27100",
                           "LocalSearchTrendsByMonth":{
                               "Apr":"40500",
                               "Mar":"33100",
                               "Feb":"27100",
                               "Jan":"27100",
                               "Dec":"27100",
                               "Nov":"27100",
                               "Oct":"27100",
                               "Sep":"27100",
                               "Aug":"27100",
                               "Jul":"27100",
                               "Jun":"27100",
                               "May":"27100"
                           },
                           "CPC":"0.24"
                       },
                       "CreatedAt":"2014-11-13",
                       "Ranking":{
                           "date":"2015-05-12",
                           “type”:”highest”,
                           "Google":{
                               "Rank":"6",
                               "BaseRank":"6",
                               "Url":"getstat.com/take-the-tour"
                           },
                           "Bing":{
                               "Rank":"29",
                               "Url":"getstat.com/take-the-tour"
                           }
                       }
                   }
                   ...
               ]
           }
       }
   }

<Ranking date="2015-05-12" type="all">
  <Google>
    <Result>
      <Rank>6</Rank>
      <BaseRank>6</BaseRank>
      <Url>getstat.com/take-the-tour</Url>
    </Result>
    <Result>
      <Rank>10</Rank>
      <BaseRank>10</BaseRank>
      <Url>getstat.com/our-clients</Url>
    </Result>
  </Google>
  <Bing/>
</Ranking>

"Ranking":{
  "date":"2015-05-12",
  “type”:”all”,
  "Google": {
     "Result": [
        {
          "Rank":"6",
          "BaseRank":"6",
          "Url":"getstat.com/take-the-tour"
        },
        {
          "Rank":"10",
          "BaseRank":"10",
          "Url":"getstat.com/our-clients"
        }
     ]
  },
  “Bing”:null
}

Return to the top

Bulk Export Jobs: Status

HTTP Method: GET

XML request URL:

/bulk/status?id={bulkjobId}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <Result>
  <Id>5</Id>
  <JobType>ranks</JobType>
  <Format>json</Format>
  <Date>2011-04-15</Date>
  <SiteId>1,5,10</SiteId>
  <Status>InProgress</Status>
  <Url></Url>
  <CreatedAt>2011-05-03</CreatedAt>
 </Result>
</Response>

JSON request URL:

/bulk/status?id={bulkjobId}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"5",
         "JobType":"ranks",
         "Format":"json",
         "Date":"2011-04-15",
         "SiteId":"1,5,10",
         "Status":"InProgress",
         "Url":null,
         "CreatedAt":"2011-05-03"
      }
   }
}

Return to the top

Bulk Export Jobs: Delete

HTTP Method: GET

XML request URL:

/bulk/delete?id={bulkjobId}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode=”200”>
 <Result>
  <Id>1</Id>
 </Result>
</Response>

JSON request URL:

/bulk/delete?id={bulkjobId}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"1"
      }
   }
}

Return to the top

Bulk Export Jobs: Site Ranking Distributions

Ranking distribution records are reported for all sites in system on the given date. (Note that you cannot create bulk jobs for the current date or dates in the future.)

HTTP Method: GET

XML request URL:

/bulk/site_ranking_distributions?date={YYYY-MM-DD}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode=”200”>
 <Result>
  <Id>1</Id>
 </Result>
</Response>

JSON request URL:

/bulk/site_ranking_distributions?date={YYYY-MM-DD}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"1"
      }
   }
}

Return to the top

Bulk Export Jobs: Tag Ranking Distributions

HTTP Method: GET

XML request URL:

/bulk/tag_ranking_distributions?date={YYYY-MM-DD}

XML typical response:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode=”200”>
 <Result>
  <Id>1</Id>
 </Result>
</Response>

JSON request URL:

/bulk/tag_ranking_distributions?date={YYYY-MM-DD}&format=json

JSON typical response:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"1"
      }
   }
}

Return to the top

Bulk: Google HTML SERP, SERP, Google Ads (Optional specialized service)

These are part of our optional specialty paid API services which can be turned on for individual sites via Site Tools > Settings.

To receive the most accurate Google Ads data from this service, it’s important to set a precise Location (city, state, province, ZIP code and/or postal code) for all of your keywords when adding them to STAT. If your keywords don’t have locations set, learn more about your options for editing your keywords.

HTTP Method: GET

XML request URL:

/bulk/list

XML typical response for an HTML SERP archive:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode=”200”>
 <Result>
  <Id>8</Id>
  <JobType>html-serps</JobType>
  <Format>xml</Format>
  <Project>Cats R Us</Project>
  <Folder>Kitten Kaboodle</Folder>
  <SiteTitle>Fancy Feast</SiteTitle>
  <SiteUrl>www.holyanchovy.com</SiteUrl>
  <SiteId>123</SiteId>
  <Date>2014-12-14</Date>
  <Status>Completed</Status>
  <Url>http://stat.getstat.com/bulk_reports/download_report/99?key=xyz123</Url>
  <CreatedAt>2014-12-15</CreatedAt>
 </Result>
 ...
</Response>

XML typical response for a SERP archive:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode=”200”>
 <Result>
  <Id>13</Id>
  <JobType>serps</JobType>
  <Format>xml</Format>
  <Project>News</Project>
  <Folder>other sites</Folder>
  <SiteTitle>abcnews.go.com</SiteTitle>
  <SiteUrl>abcnews.go.com</SiteUrl>
  <SiteId>118</SiteId>
  <Date>2014-11-05</Date>
  <Status>Completed</Status>
  <Url>http://stat.getstat.com/bulk_reports/download_report/13?key=xyz123</Url>
  <StreamUrl>http://stat.getstat.com/bulk_reports/stream_report/13?key=xyz123</StreamUrl>
  <CreatedAt>2014-11-06</CreatedAt>
 </Result>
 ...
</Response>

XML typical response for a Google Ads archive:

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode=”200”>
 <Result>
  <Id>19</Id>
  <JobType>serps</JobType>
  <Format>xml</Format>
  <Project>QA PROJECT</Project>
  <Folder/>
  <SiteTitle>Samplesite.com</SiteTitle>
  <SiteUrl>www.samplesite.com</SiteUrl>
  <SiteId>641</SiteId>
  <Date>2014-11-05</Date>
  <Status>Completed</Status>
  <Url>http://stat.getstat.com/bulk_reports/download_report/19?key=xyz123</Url>
  <StreamUrl>http://stat.getstat.com/bulk_reports/stream_report/19?key=xyz123</StreamUrl>
  <CreatedAt>2014-11-06</CreatedAt>
 </Result>
 ...
</Response>

JSON request URL:

/bulk/list?format=json

JSON typical response for an HTML SERP archive:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"8",
         "JobType":"html-serps",
         "Format":"json",
         "Project":"Cats R Us",
         "Folder":"Kitten Kaboodle",
         "SiteTitle":"Fancy Feast",
         "SiteUrl":"www.holyanchovy.com",
         "SiteId":"123",
         "Date":"2014-12-14",
         "Status":"Completed",
         "Url":"http://stat.getstat.com/bulk_reports/download_report/99?key=xyz123",
         "CreatedAt":"2014-12-15"
      }
      ...
   }
}

JSON typical response for a SERP archive:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"13",
         "JobType":"serps",
         "Format":"json",
         "Project":"News",
         "Folder":"other sites",
         "SiteTitle":"abcnews.go.com",
         "SiteUrl":"abcnews.go.com",
         "SiteId":"118",
         "Date":"2014-11-05",
         "Status":"Completed",
         "Url":"http://stat.getstat.com/bulk_reports/download_report/13?key=xyz123",
         "StreamUrl":"http://stat.getstat.com/bulk_reports/stream_report/13?key=xyz123",
         "CreatedAt":"2014-11-06"
      }
      ...
   }
}

JSON typical response for a Google Ads archive:

{
   "Response":{
      "responsecode":"200",
      "Result":{
         "Id":"19",
         "JobType":"serps",
         "Format":"json",
         "Project":"QA PROJECT",
         "Folder":null,
         "SiteTitle":"Samplesite.com",
         "SiteUrl":"www.samplesite.com",
         "SiteId":"641",
         "Date":"2014-11-05",
         "Status":"Completed",
         "Url":"http://stat.getstat.com/bulk_reports/download_report/19?key=xyz123",
         "StreamUrl":"http://stat.getstat.com/bulk_reports/stream_report/19?key=xyz123",
         "CreatedAt":"2014-11-06"
      }
      ...
   }
}

XML typical response for a SERP archive in CSV format:

<?xml version="1.0" encoding="UTF-8"?>
 <Response responsecode="200" resultsreturned="100" totalresults="5883" nextpage="/bulk/list?start=100">
    <Result>
        <Id>23456</Id>
        <JobType>serps</JobType>
        <Format>csv</Format>
        <Project>Cats R Us</Project>
         <Folder/>
        <SiteTitle>Fancy Feast</SiteTitle>
        <SiteUrl>www.holyanchovy.com</SiteUrl>
        <SiteId>123</SiteId>
        <Date>2023-06-13</Date>
        <Status>Completed</Status>
        <Url>https://s3.us-east-1.amazonaws.com/stat.getstat.com/84d64577-a173-4ed2-9163-f27286fd8244.csv.gz</Url>
        <StreamUrl>https://stat.getstat.com/bulk_reports/stream_report/82959?key=041e73fd2f97b613959e6a4fdb055b1f5122b0b6</StreamUrl>
        <CreatedAt>2023-06-14</CreatedAt>
    </Result>
 ...
</Response>

JSON typical response for a SERP archive in CSV format:

{
    "Response": {
        "responsecode": "200",
        "resultsreturned": "100",
        "totalresults": "5883",
        "nextpage": "/bulk/list?start=100&format=json",
        "Result": [
            {
                "Id": "42959",
                "JobType": "serps",
                "Format": "csv",
                "Project": "News",
                "Folder": other sites,
                "SiteTitle": "abcnews.go.com",
                "SiteUrl": "abcnews.co.com",
                "SiteId": "118",
                "Date": "2023-06-13",
                "Status": "Completed",
                "Url": "https://s3.us-east-1.amazonaws.com/stat.getstat.com/84d64577-a173-4ed2-9163-f27286fd8244.csv.gz",
                "StreamUrl": "https://stat.rc.getstat.com/bulk_reports/stream_report/82959?key=041e73fd2f97b613959e6a4fdb055b1f5122b0b6",
                "CreatedAt": "2023-06-14"
            },
            ...
   }
}

XML typical response for a Google Ads archive in CSV format:

<?xml version="1.0" encoding="UTF-8"?>
 <Response responsecode="200" resultsreturned="100" totalresults="5883" nextpage="/bulk/list?start=100">
    <Result>
         <Id>80539</Id>
          <JobType>adwords</JobType>
          <Format>csv </Format>
          <Project>QA PROJECT</Project>
          <Folder/>
          <SiteTitle>www.samplesite.com</SiteTitle>
          <SiteUrl>www.samplesite.com</SiteUrl>
          <SiteId>94</SiteId>
          <Date>2023-06-13</Date>
          <Status>Completed</Status>


         <Url>https://s3.us-east-1.amazonaws.com/stat.com/fe9d8033-d122-4694-bfaa-2db2952c9873.xml.gz </Url>
         <StreamUrl>https://stat.getstat.com/bulk_reports/stream_report/40539?key=960d852ca5265d6ba233c0a477c47d44ae320a42 </StreamUrl>
         <CreatedAt>2023-06-13 </CreatedAt>
 ...
 </Response>

JSON typical response for a Google Ads archive in CSV format:

{
    "Response": {
        "responsecode": "200",
        "resultsreturned": "100",
        "totalresults": "5883",
        "nextpage": "/bulk/list?start=100&format=json",
        "Result": [
            {
                "Id": "80539",
                "JobType": "adwords",
                "Format": "csv",
                "Project": "QA PROJECT",
                "Folder": null,
                "SiteTitle": "Samplesite",
                "SiteUrl": "www.samplesite.com",
                "SiteId": "83",
                "Date": "2023-06-13",
                "Status": "Completed",
                "Url": "https://s3.us-east-1.amazonaws.com/stat.getstat.com/fe9d8033-d122-4694-bfaa-2db2952c9873.xml.gz",
                "StreamUrl": "https://stat.getstat.com/bulk_reports/stream_report/40539?key=960d852ca5265d6ba233c0a477c47d44ae320a42",
                "CreatedAt": "2023-06-13"
            },
            ...
   }
}

<engine>-<date>-<keyword>-<market>-<location>-<device>.html

google-2015-05-12-mens shoes-GB-en--desktop.html

google-2015-05-12-mens shoes-GB-en-London-mobile.html

<?xml version="1.0" encoding="UTF-8"? >
<Response responsecode="200">
 <DateRequested>2014-12-14</DateRequested>
 <SitesRequested>Feline Fancy</SitesRequested>
 <Site id="123">
  <KeywordSerps keyword_id="2345" keyword="cat" market="US-en" location="" device="mobile">
   <Google>
        <Result>
             <ResultTypes>
                  <ResultType>amp</ResultType>
                  <ResultType>carousel</ResultType>
                  <ResultType>news</ResultType>
             </ResultTypes>
             <Rank>2</Rank>
             <BaseRank></BaseRank>
             <Protocol>http</Protocol>
             <Url>
                   www.slashgear.com
             </Url>
             <Title>Cat Backpacks</Title>
        </Result>
        <Result>
             <ResultTypes>
                  <ResultType>news</ResultType>
                  <ResultType>amp</ResultType>
                  <ResultType>carousel</ResultType>
             </ResultTypes>
             <Rank>2</Rank>
             <BaseRank></BaseRank>
             <Protocol>http</Protocol>
             <Url>
                   www.space.com
             </Url>
             <Title>Hamster Wheel</Title>
        </Result>
   </Google>
 ...
</Response>

{
   "Response":{
      "responsecode":"200",
      "DateRequested":"2014-12-14",
      "SitesRequested":"Feline Fancy",
      "Sites": [
       {
            "id":"123",
            "KeywordSerps":{
            "keyword_id":"2345",
            "keyword":"cat",
            "market":"US-en",
            "location":"",
            "device":"mobile",
   "Google":{
        "Result":[
             {
                "ResultTypes": {
                     "ResultType":[
                          "amp",
                          "carousel",
                          "news"
                      ]
                 },
                 "Rank":"2",
                 "BaseRank":"",
                 "Protocol": "http",
                 "Url":"www.slashgear.com",
                 "Title": "Cat Backpacks"
               },
              {
                "ResultTypes": {
                     "ResultType":[
                          "amp",
                          "carousel",
                          "news"
                      ]
                 },
                 "Rank":"2",
                 "BaseRank":"",
                 "Protocol": "http",
                 "Url":"www.space.com",
                 "Title": "Hamster Wheel"
               }
        ...
     ]
},
}

Site ID,Keyword ID,Keyword,Market,Location,Device,Result Type,Rank,Base Rank,Protocol,URL,Title,Translation
975,3398912,cat,US-en,,mobile,"""amp,carousel,news""",1,1,www.slashgear.com,"""Cat Backpacks""",
975,3398912,hamster,US-en,,mobile,"""regular""",2,2,www.space.com,"""Hamster Wheell""",
975,3398912,Dog,US-en,,mobile,"""regular,carousel,Image""",3,3,www.dogbehaviour.com,"""Dog Behaviour""",

<?xml version="1.0" encoding="UTF-8"?>
<Response responsecode="200">
 <DateRequested>2014-12-14</DateRequested>
 <SitesRequested>Feline Fancy</SitesRequested>
 <Site id="123">
  <KeywordAdwords keyword_id="2345" keyword="cat" market="US-en" location="" device="desktop">
   <KeywordTags>
    <Tag>yarn</Tag>
    <Tag>wool</Tag>
   </KeywordTags>
   <KeywordStats>
    <AdvertiserCompetition>0.01</AdvertiserCompetition>
    <GlobalSearchVolume>1500000</GlobalSearchVolume>
    <RegionalSearchVolume>450000</RegionalSearchVolume>
    <CPC>2.11</CPC>
   </KeywordStats>
   <Ads>
    <Ad>
     <Rank>1</Rank>
     <Title/>
     <Copy>
      Save up to 25% on Knitting and Crochet Yarns Online at Yarn.com
     </Copy>
     <DisplayUrl>www.yarn.com/</DisplayUrl>
     <DestinationUrl>http://www.yarn.com/</DestinationUrl>
     <CrawledAt>2014-12-14 00:04:17 UTC</CrawledAt>
    </Ad>
    ...
   </Ads>
  </KeywordAdwords>
  ...
 </Site>

{
  "Response":{
    "responsecode":"200",
    "DateRequested":"2014-12-14",
    "SitesRequested":"Feline Fancy",
    "Sites": [
      {
        "id":"123",
        "KeywordAdwords": [
          {
            "keyword_id":"2345",
            "keyword":"cat",
            "market":"US-en",
            "location":"",
            "device":"desktop",
            "KeywordTags": [
              "yarn", "wool"
            ],
            "KeywordStats":{
               "AdvertiserCompetition":"0.01",
               "GlobalSearchVolume":"1500000",
               "RegionalSearchVolume":"450000",
               "CPC":"2.11"
            },
            "Ads": [
              {
                "Rank":"1",
                "Title":null,
                "Copy":"Save up to 25% on Knitting and Crochet Yarns Online at Yarn.com",
                "DisplayUrl":"www.yarn.com/",
                "DestinationUrl":"http://www.yarn.com/",
                "CrawledAt":"2014-12-14 00:04:17 UTC"
              }
              ...
            ]
          }
          ...
        ]
      }
    ]
   }
}

SiteID,KeywordID,Keyword,Market,Location,Device,Translation,AdvertiserCompetition,GlobalSearchVolume,RegionalSearchVolume,CPC,Rank,Title,Copy,DisplayUrl,DestinationUrl,CrawledAt
963,3225328,yarn,US-en,"""seattle, wa""",desktop,,0.2,9900,2400,18.44,1,""Crochet & Knitting Wool & Yarn""","""Find a full range of the finest yarns and knitting wool from all your favourite brands",,https://www.lovecrafts.com/ 02:33:46 UTC
963,3225328,wool,US-en,"""seattle, wa""",desktop,,0.2,9900,2400,18.44,2,"""Knitting Yarns - Shop Now - Up To 50% June Summer Sale""","""Get Your 15% Welcome Discount and Free Delivery on Orders over £30.""",,https://https://www.woolwarehouse.co.uk 02:33:46 UTC
963,3225328,cotton reels,US-en,"""seattle, wa""",desktop,,0.2,9900,2400,18.44,3,"""Cotton cords - Reels, rolls & cut lengths""","""Trade And Wholesale Supplies Of fine cotton cords and tapes.""",,https://www.supplydivision.com/ 02:33:46 UTC

Return to the top