The Keylime Toolbox API provides programmatic access to metrics from your Keylime Toolbox reports:
In addition you can get a list of your reporting groups and the individual properties aggregated into each reporting group as available in your Keylime Toolbox reporting group settings.
The API is designed with resource-oriented URLs following REST so that they should be reasonable and expected. The API uses standard HTTP verbs and parameters that can be implemented with any HTTP client.
If you have any questions or need assistance using the API please reach out to us.
All API calls must be made over HTTPS on the app.keylime.io domain. Send
data to the API as query parameters. API responses are in JSON format or
CSV or XLSX format. The response includes a Content-type header, which specifies the format.
For JSON requests, send an Accept: application/json header or use the .json extension on your request
to specify the format.
Dates in parameters and responses use ISO 8601 extended date format:
YYYY-MM-DD
YYYY-MM-DDTHH:MM:SSZ
API requests take parameters. (An email and API token may be provided as headers or a parameter — see Authentication below.) Some parameters are specified in the path of the URL and are used to scope the resource. For GET requests, other parameters can be added to the query string.
For example, in the following:
- the email and token for authentication are provided as headers
- the reporting group slug, “example-com”, is included in the path
- the date parameter is included in the URL parameter list
$ curl -H "X-User-Email: $USER_EMAIL" -H "X-User-Token: $USER_TOKEN" 'https://app.keylime.io/site_groups/example-com/reports/aggregate_queries?date=2015-06-15'
The API uses token-based authentication. Every request must include a header or parameter to specify the user and the
token. To use headers, set X-User-Email and X-User-Token:
$ curl -H 'Accept: application/json' -H 'X-User-Email: me@example.com' -H 'X-User-Token: Ac34mdArbme0Jrn' https://app.keylime.io/site_groups
When authenticating with parameters, use user_email and a user_token:
$ curl -H 'Accept: application/json' 'https://app.keylime.io/site_groups?user_email=me@example.com&user_token=Ac34mdArbme0Jrn'
The X-User-Email header or user_email parameter is the email address on your account (that you use to sign in). You
can find the token (and you email address) in Keylime Toolbox in your profile settings.
You can reset your token at any time but you can only have one active token at a time.
For brevity, we’ve skipped the authentication headers or parameters on the examples in the rest of this documentation, but you will need those for each call.
You should make all your API requests using HTTPS, which protects the the headers and parameters.
Protect your API token as you would a password.
These error codes could be returned from any API request.
Sending a request without the correct token or for which you do not have permissions
results in a 404 Not Found error. Depending on the Content-type the response message
may be JSON or plain text.
HTTP/1.1 404 Not Found
Content-length: 35
{"error":"Keylime Toolbox couldn't find what you were looking for. If you were expecting to find this, try signing in."}
Sending a request to a resource with invalid parameters or that does not include required parameters
results in a 400 Bad Request error.
Depending on the Content-type the response message may be JSON or plain text.
HTTP/1.1 400 Bad Request
Content-length: 52
You must include a 'date' parameter in your request.
The API uses HTTP redirects in places and clients should assume that any request may result in a redirect. Redirects
include a Location: header containing the URI of the resource. Clients should request this immediately as the
resource may only be available at the provided URI for a short time.
| Status Code | Description |
|---|---|
| 301 | Moved Permanently. The requested resource has been assigned a new permanent URI specified in the Location header field. Any future references to this resource should use the new URI. |
| 302, 307 | Temporary Redirect. The requested resource resides temporarily under the URI specified in the Location header field. Clients should continue to use the original URI for future requests. |
The API currently only supports GET requests which provides read-only access to information.
A combination of domains, subdomains, and subfolders.
A reporting group may be a domain or subdomain, such as example.com or www.example.com, it may be a subfolder,
such as example.com/sale, or it may be a collection of these. Keylime Toolbox aggregates the data into a single set
of metrics. If you have included subfolders, Keylime Toolbox will aggregate the data, de-duplicating metrics
appropriately, as described in
Keylime Toolbox Data Integration.
GET /site_groups.json
The response is a JSON array of objects having name and slug attributes.
[
{
"name": "example.com",
"slug": "example-com"
},
{
"name": "example.co.uk",
"slug": "example-co-uk"
}
]
Individual properties from Google Search Console from which Keylime Toolbox collects metrics.
When you authorize Keylime Toolbox with access to your Google Search Console account or properties, Keylime Toolbox collects metrics for each of those properties. Properties are grouped into a reporting group for aggregate query metrics.
Properties are also used for Crawl Analytics where detailed data is generated for properties (usually domains and subdomains, not subfolders).
GET /site_groups/:site_group_id/sites.json
Parameters
The response is a JSON array of objects having name and slug attributes.
[
{
"url": "example.com",
"slug": "example-com"
},
{
"url": "example.com/sale",
"slug": "example-com-sale"
}
]
Which days Keylime Toolbox has metrics for your reports.
Keylime Toolbox retains all the historical Google Search Console metrics for each of your properties as long as you have an account with us. This can add up to many years of data.
For individual properties, this call will tell you for which dates Keylime Toolbox downloaded GSC metrics.
GSC crawl errors are provided one day a week. See more about crawl errors below.
This does not cover Crawl Analytics detailed reports. See Crawl Metrics below.
GET /sites/:site_id/data_points.json
Parameters
The response is a JSON array of objects having a date attribute.
YYYY-MM-DD.[
{
"date": "2015-06-14"
},
{
"date": "2015-06-15"
}
]
Keylime Toolbox aggregates queries, URL, and traffic metrics for reporting groups. You can find out for which dates Keylime Toolbox generated reports.
GET /site_groups/:site_group_id/data_points.json
Parameters
The response is a JSON array of objects having a date attribute.
YYYY-MM-DD.[
{
"date": "2015-06-14"
},
{
"date": "2015-06-15"
}
]
Aggregated Query, URL, and traffic metrics from Google Search Console.
Keylime Toolbox aggregates metrics across all Google Search Console properties in a reporting group, de-duplicating metrics appropriately. You can get this aggregated data for queries, URLs, and traffic through these API calls.
Provides a CSV file containing aggregated query metrics for the reporting group and the date given.
These metrics are aggregated across all domains, subdomains, and subfolders included in the reporting group.
If a search_appearance parameter is given, metrics are aggregated by page, rather than by
property.
GET /site_groups/:site_group_id/reports/aggregate_queries?date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_queries?date=2015-06-15&fields=*
GET /site_groups/:site_group_id/reports/aggregate_queries?date=2015-06-15&fields=Query,Search%20type,Impressions,Clicks,Avg.%20position
GET /site_groups/:site_group_id/reports/aggregate_queries?search_appearance=RICHCHARD&date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_queries?search_appearance=RICHCARD&date=2015-06-15&fields=*
GET /site_groups/:site_group_id/reports/aggregate_queries?search_appearance=RICHCARD&date=2015-06-15&fields=Query,Search%20type,Impressions,Clicks,Avg.%20position
GET /site_groups/:site_group_id/reports/aggregate_queries?unassociated=true&date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_queries?unassociated=true&search_appearance=RICHCARD&date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_queries?unassociated=true&search_appearance=RICHCARD&date=2015-06-15&fields=*
Parameters
YYYY-MM-DD format. For example, 2015-04-27. The date is required.The metrics include impressions, clicks, click through rate, and rank. Rank is averaged over impressions, which is different from what Keylime Toolbox does for reports. For more details, see Understanding Keylime Toolbox Data.
On success this will return a CSV file in the body with a header row and aggregate query metrics.
Default fields
GET /site_groups/:site_group_id/reports/aggregate_queries?date=2015-06-15
Query,Impressions,Clicks,CTR,Avg. position kittens,16716,6773,0.405,1.5 cute cats,2709,1174,0.433,1.3 frisky feline,263,191,0.726,1.0
Selected fields
GET /site_groups/:site_group_id/reports/aggregate_queries?date=2015-06-15&fields=Query,Search%20type,Impressions,Clicks,Avg.%20position
Query,Search type,Impressions,Clicks,Avg. position kittens,web,16716,6773,1.5 cute cats,image,2709,1174,1.3 frisky feline,video,263,191,1.0
All fields
GET /site_groups/:site_group_id/reports/aggregate_queries?date=2015-06-15&fields=*
Query,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,web,DESKTOP,16716,6773,0.405,1.5 cute cats,image,MOBILE,2709,1174,0.433,1.3 frisky feline,video,TABLET,263,191,0.726,1.0
Default fields with search_appearance
GET /site_groups/:site_group_id/reports/aggregate_queries?search_appearance=RICHCARD&date=2015-06-15
Query,Impressions,Clicks,CTR,Avg. position kittens,16716,6773,0.405,1.5 cute cats,2709,1174,0.433,1.3 frisky feline,263,191,0.726,1.0
Selected fields with search_appearance
GET /site_groups/:site_group_id/reports/aggregate_queries?search_appearance=RICHCARD&date=2015-06-15&fields=Query,Search%20type,Impressions,Clicks,Avg.%20position
Query,Search type,Impressions,Clicks,Avg. position kittens,web,16716,6773,1.5 cute cats,image,2709,1174,1.3 frisky feline,video,263,191,1.0
All fields with search_appearance
GET /site_groups/:site_group_id/reports/aggregate_queries?search_appearance=RICHCARD&date=2015-06-15&fields=*
Query,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,web,DESKTOP,16716,6773,0.405,1.5 cute cats,image,MOBILE,2709,1174,0.433,1.3 frisky feline,video,TABLET,263,191,0.726,1.0
With unassociated, no search_appearance, and default fields
GET /site_groups/:site_group_id/reports/aggregate_queries?unassociated=true&date=2015-06-15
Query,Impressions,Clicks,CTR,Avg. position kittens,16716,6773,0.405,1.5 cute cats,2709,1174,0.433,1.3 frisky feline,263,191,0.726,1.0 <clicks with no associated query provided in Google Search Console>,825,19,23%,1.4 <clicks with no associated query provided in Google Search Console>,142,0,0%,1.2 <clicks with no associated query provided in Google Search Console>,0,0,,1.1
With unassociated, search_appearance, and all fields
GET /site_groups/:site_group_id/reports/aggregate_queries?unassociated=true&search_appearance=RICHCARD&date=2015-06-15&fields=*
Query,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,web,DESKTOP,16716,6773,0.405,1.5 cute cats,image,MOBILE,2709,1174,0.433,1.3 frisky feline,video,TABLET,263,191,0.726,1.0 <clicks with no associated query provided in Google Search Console>,web,,825,19,23%,1.4 <clicks with no associated query provided in Google Search Console>,image,,142,0,0%,1.2 <clicks with no associated query provided in Google Search Console>,video,,0,0,,1.1
Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).search_appearance
parameter, this may mean there are no impressions for that search appearance for that date.
Otherwise, this means Google Search Console has not yet made the data available. Keylime Toolbox imports data daily
from Google Search Console, and it is typically 2-3 days ago.Provides a CSV file containing aggregated URL metrics for the reporting group and the date given.
These metrics are aggregated across all domains, subdomains, and subfolders included in the reporting group.
GET /site_groups/:site_group_id/reports/aggregate_urls?date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_urls?date=2015-06-15&fields=*
GET /site_groups/:site_group_id/reports/aggregate_urls?date=2015-06-15&fields=Page,Search%20type,Impressions,Clicks,Avg.%20position
GET /site_groups/:site_group_id/reports/aggregate_urls?search_appearance=RICHCARD&date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_urls?search_appearance=RICHCARD&date=2015-06-15&fields=*
GET /site_groups/:site_group_id/reports/aggregate_urls?search_appearance=RICHCARD&date=2015-06-15&fields=Page,Search%20type,Impressions,Clicks,Avg.%20position
GET /site_groups/:site_group_id/reports/aggregate_urls?unassociated=true&date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15&fields=*
Parameters
YYYY-MM-DD format. For example, 2015-04-27. The date is required.The metrics include impressions, clicks, click through rate, and rank.
On success this will return a CSV file in the body with headers and aggregate URL metrics.
Default fields
GET /site_groups/:site_group_id/reports/aggregate_urls?date=2015-06-15
Page,Impressions,Clicks,CTR,Avg. position https://example.com/,39252,8676,0.221,3.5 https://example.com/kittens/,1819,650,0.357,20.0 https://example.com/cats/food,3903,531,0.136,5.4
Selected fields
GET /site_groups/:site_group_id/reports/aggregate_urls?date=2015-06-15&fields=Page,Search%20type,Impressions,Clicks,Avg.%20position
Page,Search type,Impressions,Clicks,Avg. position https://example.com/,web,39252,8676,3.5 https://example.com/kittens/,image,1819,650,20.0 https://example.com/cats/food,video,3903,531,5.4
All fields
GET /site_groups/:site_group_id/reports/aggregate_urls?date=2015-06-15&fields=*
Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position https://example.com/,web,DESKTOP,39252,8676,0.221,3.5 https://example.com/kittens/,image,MOBILE,1819,650,0.357,20.0 https://example.com/cats/food,video,TABLET,3903,531,0.136,5.4
Default fields with search_appearance
GET /site_groups/:site_group_id/reports/aggregate_urls?search_appearance=RICHCARD&date=2015-06-15
Page,Impressions,Clicks,CTR,Avg. position https://example.com/,39252,8676,0.221,3.5 https://example.com/kittens/,1819,650,0.357,20.0 https://example.com/cats/food,3903,531,0.136,5.4
Selected fields with search_appearance
GET /site_groups/:site_group_id/reports/aggregate_urls?search_appearance=RICHCARD&date=2015-06-15&fields=Page,Search%20type,Impressions,Clicks,Avg.%20position
Page,Search type,Impressions,Clicks,Avg. position https://example.com/,web,39252,8676,3.5 https://example.com/kittens/,image,1819,650,20.0 https://example.com/cats/food,video,3903,531,5.4
All fields with search_appearance
GET /site_groups/:site_group_id/reports/aggregate_urls?search_appearance=RICHCARD&date=2015-06-15&fields=*
Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position https://example.com/,web,DESKTOP,39252,8676,0.221,3.5 https://example.com/kittens/,image,MOBILE,1819,650,0.357,20.0 https://example.com/cats/food,video,TABLET,3903,531,0.136,5.4
With unassociated, no search_appearance, and default fields
GET /site_groups/:site_group_id/reports/aggregate_urls?unassociated=true&date=2015-06-15
Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position https://example.com/,39252,8676,0.221,3.5 https://example.com/kittens/,1819,650,0.357,20.0 https://example.com/cats/food,3903,531,0.136,5.4 <clicks with no associated page provided in Google Search Console>,825,19,23%,1.4 <clicks with no associated page provided in Google Search Console>,142,0,0%,1.2 <clicks with no associated page provided in Google Search Console>,0,0,,1.1
With unassociated, search_appearance, and all fields
GET /site_groups/:site_group_id/reports/aggregate_urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15&fields=*
Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position https://example.com/,web,DESKTOP,39252,8676,0.221,3.5 https://example.com/kittens/,image,MOBILE,1819,650,0.357,20.0 https://example.com/cats/food,video,TABLET,3903,531,0.136,5.4 <clicks with no associated page provided in Google Search Console>,web,,825,19,23%,1.4 <clicks with no associated page provided in Google Search Console>,image,,142,0,0%,1.2 <clicks with no associated page provided in Google Search Console>,video,,0,0,,1.1
Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).search_appearance
parameter, this may mean there are no impressions for that search appearance for that date.
Otherwise, this means Google Search Console has not yet made the data available. Keylime Toolbox imports data daily
from Google Search Console, and it is typically 2-3 days ago.Provides a CSV file containing aggregated metrics for every query and URL for the reporting group and the date given.
These metrics are aggregated across all domains, subdomains, and subfolders included in the reporting group.
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?date=2015-06-15&fields=*
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?date=2015-06-15&fields=Query,Page,Search%20type,Impressions,Clicks,Avg.%20position
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?search_appearance=RICHCARD&date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?search_appearance=RICHCARD&date=2015-06-15&fields=*
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?search_appearance=RICHCARD&date=2015-06-15&fields=Query,Page,Search%20type,Impressions,Clicks,Avg.%20position
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?unassociated=true&date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15&fields=*
Parameters
YYYY-MM-DD format. For example, 2015-04-27. The date is required.The metrics include impressions, clicks, click through rate, and rank.
On success this will return a CSV file in the body with headers and aggregate Query+URL metrics.
Default fields
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?date=2015-06-15
Query,Page,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,39252,8676,0.221,3.5 cute cats,https://example.com/kittens/,1819,650,0.357,20.0 frisky felines,https://example.com/cats/food,3903,531,0.136,5.4
Selected fields
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?date=2015-06-15&fields=Query,Page,Search%20type,Impressions,Clicks,Avg.%20position
Query,Page,Search type,Impressions,Clicks,Avg. position kittens,https://example.com/,web,39252,8676,3.5 cute cats,https://example.com/kittens/,image,1819,650,20.0 frisky felines,https://example.com/cats/food,video,3903,531,5.4
All fields
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?date=2015-06-15&fields=*
Query,Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,web,DESKTOP,39252,8676,0.221,3.5 cute cats,https://example.com/kittens/,image,MOBILE,1819,650,0.357,20.0 frisky felines,https://example.com/cats/food,video,TABLET,3903,531,0.136,5.4
Default fields with search_appearance
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?search_appearance=RICHCARD&date=2015-06-15
Query,Page,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,39252,8676,0.221,3.5 cute cats,https://example.com/kittens/,1819,650,0.357,20.0 frisky felines,https://example.com/cats/food,3903,531,0.136,5.4
Selected fields with search_appearance
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?search_appearance=RICHCARD&date=2015-06-15&fields=Query,Page,Search%20type,Impressions,Clicks,Avg.%20position
Query,Page,Search type,Impressions,Clicks,Avg. position kittens,https://example.com/,web,39252,8676,3.5 cute cats,https://example.com/kittens/,image,1819,650,20.0 frisky felines,https://example.com/cats/food,video,3903,531,5.4
All fields with search_appearance
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?search_appearance=RICHCARD&date=2015-06-15&fields=*
Query,Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,web,DESKTOP,39252,8676,0.221,3.5 cute cats,https://example.com/kittens/,image,MOBILE,1819,650,0.357,20.0 frisky felines,https://example.com/cats/food,video,TABLET,3903,531,0.136,5.4
With unassociated, no search_appearance, and default fields
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?unassociated=true&date=2015-06-15
Query,Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,39252,8676,0.221,3.5 cute cats,https://example.com/kittens/,1819,650,0.357,20.0 frisky felines,https://example.com/cats/food,3903,531,0.136,5.4 <clicks with no associated page provided in Google Search Console>,825,19,23%,1.4 <clicks with no associated page provided in Google Search Console>,142,0,0%,1.2 <clicks with no associated page provided in Google Search Console>,0,0,,1.1
With unassociated, search_appearance, and all fields
GET /site_groups/:site_group_id/reports/aggregate_queries_urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15&fields=*
Query,Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,web,DESKTOP,39252,8676,0.221,3.5 cute cats,https://example.com/kittens/,image,MOBILE,1819,650,0.357,20.0 frisky felines,https://example.com/cats/food,video,TABLET,3903,531,0.136,5.4 <clicks with no associated page provided in Google Search Console>,web,,825,19,23%,1.4 <clicks with no associated page provided in Google Search Console>,image,,142,0,0%,1.2 <clicks with no associated page provided in Google Search Console>,video,,0,0,,1.1
Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).search_appearance parameter, this may mean there are no impressions for that search appearance for that date.
Otherwise, this means Google Search Console has not yet made the data available. Keylime Toolbox imports data daily
from Google Search Console, and it is typically 2-3 days ago.Lists which search appearance facets properties in the reporting group had impressions for on the given day.
GET /site_groups/:site_group_id/search_appearances?date=2015-06-15
Parameters
YYYY-MM-DD format. For example, 2015-06-15. The date is required.On success this will return a JSON array of search appearance types.
[ "AMP_BLUE_LINK", "RICHCARD" ]
Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).Google Search Console reports metrics (impressions, clicks, CTR, and rank) for most searches but excludes data from rare queries. However, Google Search Console reports the total metrics for a property (without regard to query or URL) that include these searches. We aggregate that traffic for reporting groups. However, if the reporting group has multiple domains, don’t use this API: we cannot accurately calculate the total traffic across all domains; the value reported won’t make sense.
GET /site_groups/:site_group_id/gsc_traffic?date=2017-10-09
Parameters
YYYY-MM-DD format. For example, 2017-10-09. The date is required.On success this will return a CSV file in the body with a header row and traffic metrics.
The column “Aggregation type” refers to Google Search Console aggregation. When correlating this with other metrics from Keylime Toolbox, query metrics without a search appearance value are aggregated “byProperty”; all others are aggregated “byPage”.
Date,Aggregation type,Search type,Impressions,Clicks,CTR,Avg. position 2019-03-01,byPage,web,16350699,687902,0.04207171815712588,5.67 2019-03-01,byProperty,web,6830529,638602,0.09349231955533752,7.1 2019-03-01,byPage,video,10290,371,0.03605442176870748,10.26 2019-03-01,byProperty,video,5311,359,0.06759555639239315,9.54 2019-03-01,byPage,image,94921,292,0.0030762423489006647,67.75 2019-03-01,byProperty,image,73476,289,0.0039332571179704935,62.88
Possible Errors
YYYY-MM-DD (e.g.
2017-10-9) or is not a valid date (e.g. 2017-10-32).Query, URL, and crawl error metrics from Google Search Console.
Keylime Toolbox downloads metrics from Google Search Console for each property you have registered. You can get query, URL, and crawl error metrics through this API call.
Provides a CSV file containing query metrics for the property and the date given.
If you provided a search_appearance parameter the metrics are aggregated by page, rather than by
property.
GET /sites/:site_id/gwt_downloads/queries?date=2015-06-15
GET /sites/:site_id/gwt_downloads/queries?search_appearance=RICHCARD&date=2015-06-15
GET /sites/:site_id/gwt_downloads/queries?unassociated=true&date=2015-06-15
GET /sites/:site_id/gwt_downloads/queries?unassociated=true&search_appearance=RICHCARD&date=2015-06-15
Parameters
YYYY-MM-DD format. For example, 2015-04-27. The date is required.The metrics include impressions, clicks, click through rate, and rank.
On success this will return a CSV file in the body with headers and query metrics.
Without search_appearance
~~~
GET /sites/:site_id/gwt_downloads/queries?date=2015-06-15
~~~
Query,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,web,DESKTOP,16716.0,6773.0,0.405,1.5 cute cats,image,MOBILE,2709.0,1174.0,0.433,1.3 frisky feline,video,TABLET,263.0,191.0,0.726,1.0
With search_appearance
~~~
GET /sites/:site_id/gwt_downloads/queries?search_appearance=RICHCARD&date=2015-06-15
~~~
Query,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,web,DESKTOP,16716.0,6773.0,0.405,1.5 cute cats,image,MOBILE,2709.0,1174.0,0.433,1.3 frisky feline,video,TABLET,263.0,191,0.726,1.0
With unassociated but no search_appearance
~~~
GET /sites/:site_id/gwt_downloads/queries?unassociated=true&date=2015-06-15
~~~
Query,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,web,DESKTOP,16716.0,6773.0,0.405,1.5 cute cats,image,MOBILE,2709.0,1174.0,0.433,1.3 frisky feline,video,TABLET,263.0,191,0.726,1.0 <clicks with no associated query provided in Google Search Console>,web,,825,19,0.23,1.4 <clicks with no associated query provided in Google Search Console>,image,,142,0,0.0,1.2 <clicks with no associated query provided in Google Search Console>,video,,0,0,0.0,1.1
With unassociated and search_appearance
~~~
GET /sites/:site_id/gwt_downloads/queries?unassociated=true&search_appearance=RICHCARD&date=2015-06-15
~~~
Query,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,web,DESKTOP,16716.0,6773.0,0.405,1.5 cute cats,image,MOBILE,2709.0,1174.0,0.433,1.3 frisky feline,video,TABLET,263.0,191,0.726,1.0 <clicks with no associated query provided in Google Search Console>,web,,825,19,0.23,1.4 <clicks with no associated query provided in Google Search Console>,image,,142,0,0.0,1.2 <clicks with no associated query provided in Google Search Console>,video,,0,0,0.0,1.1
Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).search_appearance
parameter, this may mean there are no impressions for that search appearance for that date
Otherwise, this means Google Search Console has not yet made the data available. Keylime Toolbox imports data daily
from Google Search Console, and it is typically 2-3 days ago.Provides a CSV file containing URL metrics for the property and the date given.
GET /sites/:site_id/gwt_downloads/urls?date=2015-06-15
GET /sites/:site_id/gwt_downloads/urls?search_appearance=RICHCARD&date=2015-06-15
GET /sites/:site_id/gwt_downloads/urls?unassociated=true&date=2015-06-15
GET /sites/:site_id/gwt_downloads/urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15
Parameters
YYYY-MM-DD format. For example, 2015-04-27. The date is required.The metrics include impressions, clicks, click through rate, and rank.
On success this will return a CSV file in the body with headers and URL metrics.
Without search_appearance
~~~
GET /sites/:site_id/gwt_downloads/urls?date=2015-06-15
~~~
Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position https://example.com/,web,DESKTOP,39252.0,8676.0,0.221,3.5 https://example.com/kittens/,image,MOBILE,1819.0,650.0,0.357,20.0 https://example.com/cats/food,video,TABLET,3903.0,531.0,0.136,5.4
With search_appearance
~~~
GET /sites/:site_id/gwt_downloads/urls?search_appearance=RICHCARD&date=2015-06-15
~~~
Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position https://example.com/,web,DESKTOP,39252.0,8676.0,0.221,3.5 https://example.com/kittens/,image,MOBILE,1819.0,650.0,0.357,20.0 https://example.com/cats/food,video,TABLET,3903.0,531.0,0.136,5.4
With unassociated but no search_appearance
~~~
GET /sites/:site_id/gwt_downloads/urls?unassociated=true&date=2015-06-15
~~~
Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position https://example.com/,web,DESKTOP,39252.0,8676.0,0.221,3.5 https://example.com/kittens/,image,MOBILE,1819.0,650.0,0.357,20.0 https://example.com/cats/food,video,TABLET,3903.0,531.0,0.136,5.4 <clicks with no associated page provided in Google Search Console>,web,,825,19,0.23,1.4 <clicks with no associated page provided in Google Search Console>,image,,142,0,0.0,1.2 <clicks with no associated page provided in Google Search Console>,video,,0,0,0.0,1.1
With unassociated and search_appearance
~~~
GET /sites/:site_id/gwt_downloads/urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15
~~~
Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position https://example.com/,web,DESKTOP,39252.0,8676.0,0.221,3.5 https://example.com/kittens/,image,MOBILE,1819.0,650.0,0.357,20.0 https://example.com/cats/food,video,TABLET,3903.0,531.0,0.136,5.4 <clicks with no associated page provided in Google Search Console>,web,,825,19,0.23,1.4 <clicks with no associated page provided in Google Search Console>,image,,142,0,0.0,1.2 <clicks with no associated page provided in Google Search Console>,video,,0,0,0.0,1.1
Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).search_appearance
parameter, this may mean there are no impressions for that search appearance for that date
Otherwise, this means Google Search Console has not yet made the data available. Keylime Toolbox imports data daily
from Google Search Console, and it is typically 2-3 days ago.Provides a CSV file containing metrics for every query and URL for the property and the date given.
GET /sites/:site_id/gwt_downloads/queries_urls?date=2015-06-15
GET /sites/:site_id/gwt_downloads/queries_urls?search_appearance=RICHCARD&date=2015-06-15
GET /sites/:site_id/gwt_downloads/queries_urls?unassociated=true&date=2015-06-15
GET /sites/:site_id/gwt_downloads/queries_urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15
Parameters
YYYY-MM-DD format. For example, 2015-04-27. The date is required.The metrics include impressions, clicks, click through rate, and rank.
On success this will return a CSV file in the body with headers and Query+URL metrics.
Without search_appearance
~~~
GET /sites/:site_id/gwt_downloads/queries_urls?date=2015-06-15
~~~
Query,Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,web,DESKTOP,39252.0,8676.0,0.221,3.5 cute cats,https://example.com/kittens/,image,MOBILE,1819.0,650.0,0.357,20.0 frisky feline,https://example.com/cats/food,video,TABLET,3903.0,531.0,0.136,5.4
With search_appearance
~~~
GET /sites/:site_id/gwt_downloads/queries_urls?search_appearance=RICHCARD&date=2015-06-15
~~~
Query,Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,web,DESKTOP,39252.0,8676.0,0.221,3.5 cute cats,https://example.com/kittens/,image,MOBILE,1819.0,650.0,0.357,20.0 frisky feline,https://example.com/cats/food,video,TABLET,3903.0,531.0,0.136,5.4
With unassociated but no search_appearance
~~~
GET /sites/:site_id/gwt_downloads/queries_urls?unassociated=true&date=2015-06-15
~~~
Query,Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,web,DESKTOP,39252.0,8676.0,0.221,3.5 cute cats,https://example.com/kittens/,image,MOBILE,1819.0,650.0,0.357,20.0 frisky feline,https://example.com/cats/food,video,TABLET,3903.0,531.0,0.136,5.4 <clicks with no associated page provided in Google Search Console>,web,,825,19,0.23,1.4 <clicks with no associated page provided in Google Search Console>,image,,142,0,0.0,1.2 <clicks with no associated page provided in Google Search Console>,video,,0,0,0.0,1.1
With unassociated and search_appearance
~~~
GET /sites/:site_id/gwt_downloads/queries_urls?unassociated=true&search_appearance=RICHCARD&date=2015-06-15
~~~
Query,Page,Search type,Device type,Impressions,Clicks,CTR,Avg. position kittens,https://example.com/,web,DESKTOP,39252.0,8676.0,0.221,3.5 cute cats,https://example.com/kittens/,image,MOBILE,1819.0,650.0,0.357,20.0 frisky feline,https://example.com/cats/food,video,TABLET,3903.0,531.0,0.136,5.4 <clicks with no associated page provided in Google Search Console>,web,,825,19,0.23,1.4 <clicks with no associated page provided in Google Search Console>,image,,142,0,0.0,1.2 <clicks with no associated page provided in Google Search Console>,video,,0,0,0.0,1.1
Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).search_appearance parameter, this may mean there are no impressions for that search appearance for that date
Otherwise, this means Google Search Console has not yet made the data available. Keylime Toolbox imports data daily
from Google Search Console, and it is typically 2-3 days ago.Lists which search appearance facets a property had impressions for on the given day.
GET /sites/:site_id/search_appearances?date=2015-06-15
Parameters
YYYY-MM-DD format. For example, 2019-04-27. The date is required.On success this will return a JSON array of search appearance types.
[ "AMP_BLUE_LINK", "RICHCARD" ]
Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).Google Search Console reports metrics (impressions, clicks, CTR, and rank) for most searches but excludes data from rare queries. However, Google Search Console reports the total metrics for a property (without regard to query or URL) that include these searches.
GET /sites/:site_id/gsc_traffic?date=2017-10-09
Parameters
YYYY-MM-DD format. For example, 2017-10-09. The date is required.On success this will return a CSV file in the body with a header row and traffic metrics.
The column “Aggregation type” refers to Google Search Console aggregation. When correlating this with other metrics from Keylime Toolbox, query metrics without a search appearance value are aggregated “byProperty”; all others are aggregated “byPage”.
Date,Aggregation type,Search type,Impressions,Clicks,CTR,Avg. position 2019-03-01,byPage,web,16350699,687902,0.04207171815712588,5.67 2019-03-01,byProperty,web,6830529,638602,0.09349231955533752,7.1 2019-03-01,byPage,video,10290,371,0.03605442176870748,10.26 2019-03-01,byProperty,video,5311,359,0.06759555639239315,9.54 2019-03-01,byPage,image,94921,292,0.0030762423489006647,67.75 2019-03-01,byProperty,image,73476,289,0.0039332571179704935,62.88
Possible Errors
YYYY-MM-DD (e.g.
2017-10-9) or is not a valid date (e.g. 2017-10-32).Provides a CSV file containing Google-reported crawl errors for the property and the date given. Crawl errors are available for one day each week. Each file is the most current set of all crawl errors reported by Google Search Console, so generally you only need the most recent file.
GET /sites/:site_id/gwt_downloads/crawl_errors?date=2015-06-15
Parameters
YYYY-MM-DD format. For example, 2015-04-27. The date is required.On success this will return a CSV file in the body with headers and crawl errors. The final columns, “Linked From” and “Containing Sitemaps” are a space-separated list of URLs.
URL,Issue Type,Platform,Last Crawled,First Detected,Server Status Code,Linked From,Linked From URLs,Containing Sitemaps http://example.com/kitten,notFound,web,2016-08-19T07:57:13+00:00,2016-08-19T07:57:13+00:00,404,1,http://example.com/ http://example.com/cute-cats,notFound,web,2016-06-13T10:06:38+00:00,2016-05-06T12:34:41+00:00,404,1,http://example.com/feline http://example.com/frisky-feline,notFound,web,2016-08-20T22:16:37+00:00,2016-08-20T22:16:37+00:00,404,3,http://example.com/feline
Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).An Excel file with detailed crawl metrics for the given property and date.
When you have enabled Crawl Analytics, Keylime Toolbox generates an Excel file for each day that you have provided server logs. This Excel file lists all URLs crawled by each crawler for each status code, and other metrics useful for identifying technical crawl problems and crawl budget.
Provides an Excel file containing details crawl metrics for the property and the date given.
On success this will return a 302 status code and a location to a URL that provides, as the body, an XLSX
file. This URL is only available for a short time, so you should follow the redirect immediately.
GET /sites/:site_id/reports/log_details?date=2015-04-08
Parameters
YYYY-MM-DD format. For example, 2015-04-27. The date is required.Possible Errors
YYYY-MM-DD (e.g.
2015-5-14) or is not a valid date (e.g. 2015-04-31).