Academy

Table of contents

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 Reporting API 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/json

Note: 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/websites

The 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": 500 } ]

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>/alerts

The 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>/issues

The 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>/segments

The 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/website

Or 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", "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" } ], "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", "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", "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=18

Pagination

Query parameters "per_page" and "page" are used for iterating over large result sets.

  • "per_page" can be in range from 1 to 500
  • "page" can be 1 up to "ceil(total / per_page)". If "page" is higher than max value the "urls" field will be an empty array

Response for a page

Each API response contains 2 main keys:

  • "total" count of urls in result set for given query
  • "urls" paginated urls based on query parameters per_page and page
200 OK { "total": 1, "urls": [ { "app_url": "https://app.contentkingapp.com/websites/1-2/pages/3", "analytics_services": [ "google_analytics" ], "canonical_type": "internal_self", "ga_average_time": 5.788, "ga_bounce_rate": 48, "ga_page_value": 0, "ga_page_views": 248, "ga_unique_page_views": 214, "gsc_clicks": 3, "gsc_ctr": 0.183, "gsc_impressions": 1635, "gsc_position": 41.021, "health": 950, "h1": "H1 page header", "hreflang_language": "en", "is_disallowed_in_robots_txt": false, "is_indexable": true, "is_indexable_due_to_meta_robots": true, "is_indexable_due_to_x_robots_tag": null, "is_linked": true, "link_amp": null, "link_next": null, "link_prev": null, "meta_description": "ContentKing keeps track of your website 24/7 so that you can catch unexpected changes and issues before search engines and visitors do. Try it today!", "mobile_variant": null, "number_of_hreflangs": 6, "number_of_incoming_internal_canonicals": 1, "number_of_incoming_internal_links": 314, "number_of_incoming_internal_redirects": 0, "number_of_outgoing_external_links": 10, "number_of_outgoing_internal_links": 65, "open_graph_description": "Get more visitors and increase conversions with ContentKing. Monitor your website and catch problems before search engines and visitors do. Try now!", "open_graph_image": "https://www.contentkingapp.com/wp-content/uploads/2017/12/%5B600x314%5D%20Facebook%20Open%20Graph%20-%[email protected]", "open_graph_title": "Content Optimization and Monitoring service ContentKing", "open_graph_type": "website", "open_graph_url": "https://www.contentkingapp.com/", "relevance": 5.97, "schema_org_number_of_types": 1, "schema_org_types": [ "Website" ], "segments": [ "18" ], "status_code": 200, "tag_managers": [ "google_tag_manager" ], "time_document_download": 947, "title": "Real-time SEO Auditing and Content Change Tracking - ContentKing", "twitter_card": "summary_large_image", "twitter_description": "Get more visitors and increase conversions with ContentKing. Catch problems before search engines and visitors do. Try it today!", "twitter_image": "https://www.contentkingapp.com/wp-content/uploads/2017/12/%5B600x314%5D%20Facebook%20Open%20Graph%20-%[email protected]", "twitter_site": "@contentking", "twitter_title": "Content Optimization service ContentKing", "type": "page", "url": "https://www.contentkingapp.com/", "url_depth": 0, "visual_analytics_services": [ "mouseflow" ] } ] }

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=100

Pagination

Query parameters "per_page" and "page" are used for iterating over large result sets.

  • "per_page" can be in range from 1 to 500
  • "page" can be 1 up to "ceil(total / per_page)". If "page" is higher than max value the "urls" field will be an empty array

Response for a page

Each API response contains 2 main keys:

  • "total" count of urls in result set for given query
  • "urls" paginated urls based on query parameters per_page and page
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=100

Pagination

Query parameters "per_page" and "page" are used for iterating over large result sets.

  • "per_page" can be in range from 1 to 500
  • "page" can be 1 up to "ceil(total / per_page)". If "page" is higher than max value the "urls" field will be an empty array

Response for a page

Each API response contains 2 main keys:

  • "total" count of urls in result set for given query
  • "urls" paginated urls based on query parameters per_page and page
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
content_headings/h1_duplicate H1 heading is not unique
content_headings/h1_incorrect_length H1 heading has incorrect length
content_headings/h1_missing H1 heading is missing
content_headings/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_information/meta_description_duplicate Meta description is not unique
meta_information/meta_description_incorrect_length Meta description has incorrect length
meta_information/meta_description_missing Meta description is missing
meta_information/meta_description_too_many There are multiple meta descriptions on the page
meta_information/title_duplicate Page title is not unique
meta_information/title_incorrect_length Page title has incorrect length
meta_information/title_missing Title is missing
meta_information/title_too_many There are multiple titles on pages
Open Graph
open_graph/description_incorrect_length Open Graph description has incorrect length
open_graph/missing Not all required Open Graph elements present
open_graph/title_incorrect_length Open Graph title has incorrect length
Twitter Cards
twitter_cards/description_incorrect_length Twitter Cards description has incorrect length
twitter_cards/missing Not all required Twitter Cards elements present
twitter_cards/title_incorrect_length Twitter Cards title has incorrect length
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.

Trusted by
Fantastic reviews
  • +
  • +
  • +
  • +
  • +
50+ reviews

Start your free 14-day trial

Get up and running in 20 seconds

Please enter a valid domain name (www.example.com).
  • No credit card required
  • No installation needed
  • No strings attached