Reporting API
- Basic (not available)
- Standard (available)
- Pro (available)
- Enterprise (available)
Our Reporting API is used for extracting data and metrics from your ContentKing account. Typical use-cases include connecting several software solutions together to streamline your reporting tasks and integrating ContentKing in your client portal.
Reporting API Terms of Use
By using the Reporting API you agree to the Terms of Use.
Retrieving your Reporting API token
To use the Reporting API you need to get your ContentKing account's Reporting API token. You'll find it in the Account section, under the Account Settings tab.
API request headers
When making a request you need to send along the following request headers:
Authorization: token <place-your-API-token-here>
Content-Type: application/jsonNote: you need to provide the string "token" followed by a space and your actual API token.
Reporting API URL
ContentKing Reporting API is available on this URL.
https://api.contentkingapp.com/Retrieving a list of websites in your account
Send the following request to get a list of websites in your account:
GET /v1/websitesThe response will look like this:
200 OK
[
{
"id": "1-234",
"app_url": "https://app.contentkingapp.com/websites/1-234/dashboard",
"domain": "https://www.contentkingapp.com",
"name": null,
"page_capacity": 1000
},
{
"id": "1-2345",
"app_url": "https://app.contentkingapp.com/websites/1-2345/dashboard",
"domain": "https://www.contentkingapp.de",
"name": "ContentKing - DE",
"page_capacity": 1000
}
]Retrieving a list of alerts for a website
Send the following request to get a list of alerts for a specific website in your account:
GET /v1/websites/<website_id>/alertsThe response will look like this:
200 OK
[
{
"id": "1",
"app_url": "https://app.contentkingapp.com/websites/1-234/events?event=1",
"date_last_updated": "2018-05-10T12:59:21+02:00",
"date_opened": "2018-05-10T12:59:21+02:00",
"name": "robots_txt_changed",
"scope": "platform",
"type": "warning"
},
{
"id": "2",
"app_url": "https://app.contentkingapp.com/websites/1-234/events?event=2",
"date_last_updated": "2018-07-21T03:21:46+02:00",
"date_opened": "2018-07-16T14:33:43+02:00",
"name": "issue_opened.meta_information/title_missing",
"scope": "pages",
"type": "alert"
}
]Retrieving a list of issues for a website
Send the following request to get a list of issues for a specific website in your account:
GET /v1/websites/<website_id>/issuesThe response will look like this:
200 OK
[
{
"name": "content_headings/h1_duplicate",
"points_gained": 24,
"points_to_gain": 0,
"scope": "pages"
},
{
"name": "xml_sitemap/missing",
"points_gained": 10,
"points_to_gain": 0,
"scope": "platform"
}
]Retrieving a list of segments for a website
Send the following request to get a list of segments for a specific website in your account:
GET /v1/websites/<website_id>/segmentsThe response will look like this:
200 OK
[
{
"id": "1",
"color": "72c035",
"label": "Indexable",
"shortcode": "I"
},
{
"id": "2",
"color": "9ea6af",
"label": "Non-indexable",
"shortcode": null
}
]Retrieving statistics for a website or website's segment
Send the following request to get statistics for a specific website in your account:
GET /v1/websites/<website_id>/statistics/websiteOr send the following request to get statistics for a specific segment within the website:
GET /v1/websites/<website_id>/statistics/segment:<segment_id>The response will look like this:
200 OK
{
"health": 969,
"number_of_issues": 15,
"number_of_urls":
{
"missing": 2,
"page": 9,
"redirect": 4,
"server_error": 0,
"unreachable": 0
}
}Specific errors when requesting statistics
404 Not found
{
"error": "No statistics found for given scope"
}This response means that the statistics for the given scope (website or segment) are not available at this time. They may or may not become available at a later time.
Retrieving data for a specific page within a website
Send the following request to get data for a specific page within a website in your account:
GET /v1/websites/<website_id>/pages?url=<url>Response for a page
The response for an existing page (URL returns HTTP status 200) will look like this:
200 OK
{
"url": "https://www.contentkingapp.com/",
"is_https": true,
"ga_average_time": 10,
"ga_bounce_rate": 5,
"ga_date_range":
{
"since": "2018-05-09",
"until": "2018-08-07"
},
"ga_page_value": 0,
"ga_page_views": 1,
"ga_unique_page_views": 2,
"gsc_clicks": 0,
"gsc_ctr": 0,
"gsc_date_range":
{
"since": "2018-05-09",
"until": "2018-08-07"
},
"gsc_impressions": 4,
"gsc_position": 5,
"health": 935,
"is_disallowed_in_robots_txt": false,
"is_indexable": true,
"is_indexable_due_to_meta_robots": "yes",
"is_indexable_due_to_x_robots_tag": "yes",
"is_in_sitemap": true,
"relevance": 8.72,
"status_code": 200,
"time_document_download": 183,
"type": "page",
"content": [
{
"type": "canonical",
"content": null
},
{
"type": "title",
"content": "Blog"
},
{
"type": "meta_description",
"content": "some meta description"
},
{
"type": "h1",
"content": "ContentKing"
},
{
"type": "h2",
"content": "Pricing"
},
{
"type": "meta_robots",
"content": null
},
{
"type": "open_graph_description",
"content": null
},
{
"type": "open_graph_image",
"content": null
},
{
"type": "open_graph_title",
"content": null
},
{
"type": "open_graph_type",
"content": null
},
{
"type": "open_graph_url",
"content": null
},
{
"type": "twitter_card",
"content": null
},
{
"type": "twitter_site",
"content": null
},
{
"type": "google_analytics",
"content": "UA-XXXXXX-X"
}
],
"custom_elements": {
"author": "Josie Walters",
"date_published": "12 August 2019"
},
"schema_org": [],
"segments": [
"1",
"3"
],
"app_url": "https://app.contentkingapp.com/websites/1-234/pages/3",
"open_issues": [
{
"name": "open_graph/missing"
},
{
"name": "twitter_cards/missing"
},
{
"name": "meta_information/meta_description_incorrect_length"
},
{
"name": "meta_information/title_incorrect_length"
}
]
}Response for a redirect
The response for a redirect (URL returns HTTP status 3xx) will look like this:
200 OK
{
"url": "https://www.contentkingapp.com/this-redirects",
"is_https": true,
"gsc_clicks": 9,
"gsc_ctr": 5,
"gsc_date_range":
{
"since": "2018-05-09",
"until": "2018-08-07"
},
"gsc_impressions": 1,
"gsc_position": 4,
"is_disallowed_in_robots_txt": false,
"is_indexable": false,
"is_indexable_due_to_meta_robots": "not_applicable",
"is_indexable_due_to_x_robots_tag": "not_applicable",
"is_in_sitemap": true,
"redirect":
{
"location": "https://www.contentkingapp.com/",
"url": "https://www.contentkingapp.com/",
},
"status_code": 302,
"time_document_download": 149,
"type": "redirect",
"segments": [
"1"
],
"app_url": "https://app.contentkingapp.com/websites/1-234/pages/4",
}Response for missing
The response for a missing page (URL returns HTTP status 4xx) will look like this:
200 OK
{
"url": "https://www.contentkingapp.com/this-does-not-exist",
"is_https": true,
"is_disallowed_in_robots_txt": false,
"is_indexable": false,
"is_indexable_due_to_meta_robots": "not_applicable",
"is_indexable_due_to_x_robots_tag": "not_applicable",
"is_in_sitemap": true,
"status_code": 404,
"time_document_download": 218,
"type": "missing",
"segments": [
"2"
],
"app_url":"https://app.contentkingapp.com/websites/1-234/pages/5",
}Specific errors when requesting page data
404 Not found
{
"error": "Requested URL was not found"
}This response means that the URL passed in the request is not monitored by ContentKing.
404 Not found
{
"error": "Requested URL cannot be provided via Reporting API"
}This response means that data for the URL passed in the request is not available via the Reporting API.
Retrieving list of pages for a website
Send the following request to get list of pages for a specific website:
GET /v1/websites/<website_id>/pages/list?page=1&per_page=100&sort=url&direction=desc
GET /v1/websites/<website_id>/pages/list?page=1&per_page=100&sort=url&direction=desc&filter%5Bsegment%5D=18Pagination
Query parameters per_page and page are used for iterating over large result sets.
-
per_pagecan be in range from 1 to 500 -
pagecan be 1 up toceil(total / per_page). Ifpageis higher than max value theurlsfield will be an empty array
Response
Each API response contains 2 main keys:
-
totalcount of urls in result set for given query -
urlspaginated urls based on query parametersper_pageandpage
The response for this API request will contain the list of pages for the website or the selected segment together with all the available columns (in a similar table view as you can see on the Pages screen).
Retrieving list of pages for a website alert
Send the following request to get list of pages for a specific website alert:
GET /v1/websites/<website_id>/alerts/<alert_id>/pages?page=1&per_page=100Pagination
Query parameters per_page and page are used for iterating over large result sets.
-
per_pagecan be in range from 1 to 500 -
pagecan be 1 up toceil(total / per_page). Ifpageis higher than max value theurlsfield will be an empty array
Response for a page
Each API response contains 2 main keys:
-
totalcount of urls in result set for given query -
urlspaginated urls based on query parametersper_pageandpage
200 OK
{
"total": 1,
"urls": [
{
"app_url": "https://app.contentkingapp.com/websites/1-2/pages/3",
"relevance": 5.97,
"segments": [
"18"
],
"url": "https://www.contentkingapp.com/"
}
]
}Retrieving list of pages for a website issue
Send the following request to get list of pages for a specific website issue:
GET /v1/websites/<website_id>/issues/<issue>/pages?page=1&per_page=100Pagination
Query parameters per_page and page are used for iterating over large result sets.
-
per_pagecan be in range from 1 to 500 -
pagecan be 1 up toceil(total / per_page). Ifpageis higher than max value theurlsfield will be an empty array
Response for a page
Each API response contains 2 main keys:
-
totalcount of urls in result set for given query -
urlspaginated urls based on query parametersper_pageandpage
200 OK
{
"total": 1,
"urls": [
{
"app_url": "https://app.contentkingapp.com/websites/1-2/pages/3",
"relevance": 5.97,
"segments": [
"18"
],
"url": "https://www.contentkingapp.com/"
}
]
}List of issues
| Issue | Description |
|---|---|
| Analytics | |
| analytics/analytics_missing | No analytics installed |
| analytics/visual_analytics_missing | No visual analytics installed |
| Content Headings | |
| h1/duplicate | H1 heading is not unique |
| h1/incorrect_length | H1 heading has incorrect length |
| h1/missing | H1 heading is missing |
| h1/too_many | More than one H1 heading |
| Canonical Link | |
| canonical_link/incorrectly_canonicalized | Canonical link to other page present on non-indexable page |
| canonical_link/missing | Canonical link is missing |
| canonical_link/points_to_unindexable | Canonical link is pointing to non-indexable page |
| canonical_link/too_many | More than one canonical link |
| Images | |
| images/alt_attribute | Images are missing alt-attribute |
| images/title_attribute | Images are missing title-attribute |
| Links | |
| links/broken | Page contains broken links |
| links/redirected | Page contains links to redirects |
| links/to_canonicalized | Page contains links to canonicalized URLs |
| Meta Information | |
| meta_description/duplicate | Meta description is not unique |
| meta_description/incorrect_length | Meta description has incorrect length |
| meta_description/missing | Meta description is missing |
| meta_description/too_many | There are multiple meta descriptions on the page |
| title/duplicate | Page title is not unique |
| title/incorrect_length | Page title has incorrect length |
| title/missing | Title is missing |
| title/too_many | There are multiple titles on pages |
| Open Graph | |
| open_graph/description_incorrect_length | Open Graph description has incorrect length |
| open_graph/description_missing | Open Graph description is missing |
| open_graph/image_missing | Open Graph image is missing |
| open_graph/title_incorrect_length | Open Graph title has incorrect length |
| open_graph/title_missing | Open Graph title is missing |
| open_graph/url_missing | Open Graph URL is missing |
| Twitter Cards | |
| twitter_cards/description_incorrect_length | Twitter Cards description has incorrect length |
| twitter_cards/description_missing | Twitter Cards description is missing |
| twitter_cards/image_missing | Twitter Cards image is missing |
| twitter_cards/site_missing | Twitter Cards site property is missing |
| twitter_cards/title_incorrect_length | Twitter Cards title has incorrect length |
| twitter_cards/title_missing | Twitter Cards title is missing |
| twitter_cards/type_invalid | Twitter Cards type value is not valid |
| twitter_cards/type_missing | Twitter Cards type is not present |
| XML Sitemap | |
| xml_sitemap/incorrectly_missing | Page is not included in XML sitemap |
| xml_sitemap/incorrectly_present | Pages incorrectly present in XML sitemap |
Common API errors
Authorization missing
401 Unauthorized
{
"code": "auth_missing_token",
"message": "Authentication token must be passed in Authorization HTTP header.",
"errors": []
}This response means that the request was received, but that it's lacking an authorization token and can therefore not be processed. Make sure to correctly set the Authorization header.
Authorization failed
401 Unauthorized
{
"code": "auth_failed",
"message": "Authentication token is expired or invalid.",
"errors": []
}If you get this response it means that the request could not be processed because the supplied API token is invalid or expired.
Reporting API Terms of Use not accepted
403 Forbidden
{
"code": "terms_of_use_not_accepted",
"message": "Reporting API Terms of Use have not been accepted yet. Please accept Terms of Use in Account Settings.",
"errors": []
}If you get this response it means that you have not accepted Reporting API Terms of Use yet. You need to accept them in Account Settings before you start using Reporting API.
Website not found
404 Not found
{
"error": "Requested website ID was not found"
}In case you get this response the website ID you specified can't be found in your account.
Authorization malformed
422 Unprocessable Entity
{
"code": "auth_malformed",
"message": "Authorization HTTP header must conform to format described in docs.",
"errors": []
}This response means that the request was received, but that the authorization wasn't formatted correctly. Make sure to correctly set the Authorization header.
