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

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

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