Academy

Onze Reporting API wordt gebruikt om gegevens en metrieken van jouw ContentKing account te ontsluiten. Typische use-cases zijn bijvoorbeeld het verbinden van andere software oplossingen om jouw rapportage taken te streamlinen of het integreren van ContentKing in jouw client portal.

Reporting API gebruiksvoorwaarden

Bij het gebruik van de Reporting API accepteer je de Reporting API gebruiksvoorwaarden.

Jouw Reporting API token ophalen

Om de Reporting API te kunnen gebruiken zul je het Reporting API token van jouw account moeten ophalen. Dit vind je in de Account sectie onder Account instellingen.

API request headers

Wanneer je een verzoek maakt, zul je volgende request header mee moeten sturen.

Authorization: token <place-your-API-token-here>
Content-Type: application/json

N.B.: geef de string “token” gevolgd door een spatie en het daadwerkelijke API token op.

Reporting API URL

ContentKing Reporting API is beschikbaar op deze URL.

https://api.contentkingapp.com/

Een lijst met websites in jouw account ophalen

Stuur het volgende verzoek om een lijst met websites in jouw account op te halen.

GET /v1/websites

De response ziet er zo uit:

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
	}
]

Een lijst met alerts van een website ophalen

Stuur het volgende verzoek om een lijst met alerts van een bepaalde website in jouw account op te halen:

GET /v1/websites/<website_id>/alerts

De response ziet er zo uit:

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"
	}
]

Een lijst met issues van een website ophalen

Stuur het volgende verzoek om een lijst met issues van een bepaalde website in jouw account op te halen.

GET /v1/websites/<website_id>/issues

De response ziet er zo uit:

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"
	}
]

Een lijst met segmenten van een website ophalen

Stuur het volgende verzoek om een lijst met segmenten van een bepaalde website op te halen:

GET /v1/websites/<website_id>/segments

De response ziet er zo uit:

200 OK
[
	{
		"id": "1",
		"color": "72c035",
		"label": "Indexable",
		"shortcode": "I"
	},
	{
		"id": "2",
		"color": "9ea6af",
		"label": "Non-indexable",
		"shortcode": null
	}
]

Statistieken voor een website of een segment van een website ophalen

Stuur het volgende verzoek om statistieken van een bepaalde website in jouw account op te halen:

GET /v1/websites/<website_id>/statistics/website

Of stuur het volgende verzoek om de statistieken van een bepaald segment in de website op te halen:

GET /v1/websites/<website_id>/statistics/segment:<segment_id>

De response ziet er zo uit:

200 OK
{
	"health": 969,
	"number_of_issues": 15,
	"number_of_urls":
	{
		"missing": 2,
		"page": 9,
		"redirect": 4,
		"server_error": 0,
		"unreachable": 0
	}
}

Foutmeldingen bij het opvragen van statistieken

404 Not found
{
	"error": "No statistics found for given scope"
}

Deze response betekent dat de statistieken voor een bepaald bereik (website or segment) niet beschikbaar zijn. Zij zijn mogelijk beschikbaar op een later moment.

Gegevens van een bepaalde pagina van een website ophalen

Stuur het volgende verzoek om gegevens van een bepaalde pagina van een website in jouw account op te halen:

GET /v1/websites/<website_id>/pages?url=<url>

Response voor een pagina

De response voor een bestaande pagina (URL returns HTTP status 200) ziet er zo uit:

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 voor een redirect

De response voor een redirect (URL geeft HTTP status 3xx terug) ziet er zo uit:

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 voor ontbrekende pagina

De response voor een ontbrekende pagina (URL geeft HTTP status 4xx terug) ziet er zo uit:

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",
}

Specifieke foutmeldingen bij het opvragen van paginagegevens

404 Not found
{
	"error": "Requested URL was not found"
}

Deze response betekent dat de URL in de request niet door ContentKing gemonitord wordt.

404 Not found
{
	"error": "Requested URL cannot be provided via Reporting API"
}

Deze response betekent dat gegevens voor de URL in de request niet via de Reporting API beschikbaar zijn.

Een paginalijst voor een website ophalen

Stuur het volgende verzoek om een paginalijst voor een bepaalde website te verkrijgen:

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

Paginatie

Query parameters per_page en page worden gebruikt voor het itereren over grotere result sets.

  • per_page mag tussen 1 en 500 zijn
  • page mag 1 tot ceil(total / per_page) zijn. Als “page” hoger dan de maximale waarde is dan is het urls veld een lege array

Response voor een pagina

Elke API response bevat 2 primaire keys:

  • total aantal urls in result set voor een bepaalde query
  • urls gepagineerde urls gebaseerd op query parameters per_page en 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",
			"custom_elements": {
				"author": "Josie Walters",
				"date_published": "12 August 2019"
			},
			"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_in_sitemap": true,
			"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"
			]
		}
	]
}

Een lijst met pagina’s voor een bepaalde website alert ophalen

Stuur het volgende verzoek om een lijst met pagina’s voor een bepaalde website alert op te halen:

GET /v1/websites/<website_id>/alerts/<alert_id>/pages?page=1&per_page=100

Paginatie

Query parameters per_page en page worden gebruikt voor het itereren over grotere result sets.

  • per_page mag tussen 1 en 500 zijn
  • page mag 1 tot ceil(total / per_page) zijn. Als “page” hoger dan de maximale waarde is dan is het urls veld een lege array

Response voor een pagina

Elke API response bevat 2 primaire keys:

  • total aantal urls in result set voor een bepaalde query
  • urls gepagineerde urls gebaseerd op query parameters per_page en 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/"
		}
	]
}

Een lijst met pagina’s van een website issue ophalen

Stuur het volgende verzoek om een lijst met pagina’s van een bepaalde website issue op te halen:

GET /v1/websites/<website_id>/issues/<issue>/pages?page=1&per_page=100

Paginatie

Query parameters per_page en page worden gebruikt voor het itereren over grotere result sets.

  • per_page mag tussen 1 en 500 zijn
  • page mag 1 tot ceil(total / per_page) zijn. Als “page” hoger dan de maximale waarde is dan is het urls veld een lege array

Response voor een pagina

Elke API response bevat 2 primaire keys:

  • total aantal urls in result set voor een bepaalde query
  • urls gepagineerde urls gebaseerd op query parameters per_page en 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/"
		}
	]
}

Lijst met 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

Veel voorkomende API errors

Authorisatie ontbreekt

401 Unauthorized
{
	"code": "auth_missing_token",
	"message": "Authentication token must be passed in Authorization HTTP header.",
	"errors": []
}

Dit antwoord betekent dat het verzoek ontvangen is, maar dat een authorisatie token ontbreekt en daarom niet verwerkt kan worden. Zorg ervoor dat de Authorization header correct ingesteld is.

Authorisatie mislukt

401 Unauthorized
{
	"code": "auth_failed",
	"message": "Authentication token is expired or invalid.",
	"errors": []
}

Als je dit antwoord krijgt, betekent het dat het verzoek niet verwerkt kan worden omdat het opgegeven API token ongeldig of vervallen is.

Reporting API Gebruiksvoorwaarden niet geaccepteerd

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

Als je deze response krijgt betekent dit dat je Reporting API Gebruiksvoorwaarden nog niet geaccepteerd hebt. Je zult deze moeten accepteren in de Account instellingen voordat je de Reporting API kunt gebruiken.

Website niet gevonden

404 Not found
{
	"error": "Requested website ID was not found"
}

Als je deze response krijgt kan de website ID die je hebt gespecificeerd niet in jouw account gevonden worden.

Authorisatie misvormd

422 Unprocessable Entity
{
	"code": "auth_malformed",
	"message": "Authorization HTTP header must conform to format described in docs.",
	"errors": []
}

Deze response betekent dat het verzoek ontvangen is, maar dat de authorisatie niet correct geformatteerd is. Zorg ervoor dat de Authorization header correct ingesteld is.

Probeer 14 dagen gratis

Binnen 20 seconden aan de slag

Gelieve een geldige domeinnaam (www.voorbeeld.nl) op te geven.
  • Geen credit card nodig
  • Geen installatie nodig
  • Geen verplichtingen