Open Platform: API Documentation

/content/tags

Search for keyword tags within the API.

Content in the API is classified by tags. These tags are created and applied to content by guardian.co.uk editors.

Tags can be used for two purposes: categorising an individual piece of content or acting as a search filter. When acting as a search filter tags can be combined to produce custom searches. Tags are combined using the AND operator.

The guardian.co.uk information architecture contains many types of tags. All tags are visible in the content and search apis. The /content/tag endpoint currently only exposes keywords, which represent subjects such as "the environment" or "US presidential elections".

This endpoint allows you to browse our keywords, search for particular keywords and create content searches based upon keywords or combinations of keywords.

Parameters

q	A string to search for, if omitted all keywords are returned. If present keywords matching the string will be returned
count	Specifies how many items to return as part of this query, if omitted 10 subjects are returned
start-index	Allows pagination through results by specifying which result to start from.
format	Specifies what format to return results in, the supported values are: xml and json. If this is not specified results are returned in xml format.

Examples

• /content/tags - find all available keywords
• /content/tags?format=json - find all available keywords. Return results in JSON format.
• /content/tags?q=healthcare - find all keywords matching healthcare

Response structure

Returns a collection of tag elements representing keywords, and a count of the number of keywords that matched the query. The fields returned on tag are:

• name which identifies the tag and can be used for display. This name is not neccesarily unique.
• type the type of the tag. This endpoint will only return keywords.
• filter A string of text that can be passed into the search endpoint to find all content with this tag. This identifier is unique and can be considered as the ID of the tag.
• api-url The URL of the search endpoint representing this tag. This endpoint will apply the above filter.
• web-url The URL of the guardian.co.uk web page representing this tag.