The Guardian Connector - Ismena website

info@ismena.com

The Guardian Connector

Connector Details

Type

Virtual machines, Single VM , BYOL

Runs on

Google Compute Engine

Last Update

24 October, 2024

Category

Overview

The Guardian Connector provides seamless integration enabling developers and applications to access and interact with The Guardian’s extensive content database. It functions as a lightweight proxy service, receiving requests from client applications and securely forwarding them to the Guardian API, then returning responses in a standardized JSON format.
By abstracting the underlying API, the connector simplifies client integration, ensuring that applications can easily query, filter, and retrieve news content without directly handling low-level API complexities. This makes it suitable for use in content aggregation platforms, news dashboards, and analytical tools that require structured access to Guardian articles and metadata.

Integration Overview

This document provides a detailed guide for each integration point, its purpose, configuration, required parameters, and example workflows.
Supported Integration Action Points

search – Search for content based on filters.
getTags – Retrieve tags used in Guardian content.
getSections – Retrieve available content sections.
getEditions – Retrieve available regional editions (UK, US, AU).
getItemById – Retrieve a single content item by ID.

Detailed Integration Documentation

2.1 Search

Action	search
Purpose	Retrieves articles and other content matching specified criteria such as keywords, tags, sections, and date ranges.
Parameters	Required: api-key (string) – Your Guardian Open Platform API key. Optional: q (string) – Search terms (supports AND, OR, NOT). from-date (string, YYYY-MM-DD) – Start date. to-date (string, YYYY-MM-DD) – End date. section (string) – Filter by section (comma-separated). tag (string) – Filter by tag (comma-separated). production-office (string) – Filter by production office (aus, us, uk). use-date (string) – Use this date instead of webPublicationDate for filtering. ids (string) – Comma-separated list of content IDs. show-fields (string) – Fields to include (e.g., all, bodyText, byline). show-tags (string) – Types of tags to include (contributor, keyword, series, tone). show-refinements (boolean) – Whether to include refinements (true/false). show-blocks (string) – Show blocks (body, all). page-size (integer, 1–100, default: 10) – Number of items per page. page (integer, default: 1) – Page number. order-by (string) – Order results (newest, oldest, relevance, etc.). lang (string) – Language filter (ISO code). format (string, default: json) – Response format (json or xml).
Output	Success: JSON object with: status – success/failure. userTier pagination – total, currentPage, etc. results – array of content objects (id, type, section, title, publication date, URL, fields). Failure: Error details (e.g., invalid API key).
Workflow Example	Execute `search?q=climate+change§ion=environment&api-key=YOUR_KEY`. Retrieve articles matching “climate change” in the environment section. Use the results for displaying a news feed.

2.2 Tags

Action	getTags
Purpose	Retrieves tags used in Guardian content. Tags include contributors, keywords, series, and tones.
Parameters	Required: api-key (string) – Your API key. Optional: q (string) – Search term for tags. section (string) – Filter tags by section. tag (string) – Filter by tag ID. page-size (integer, default: 10) – Number of items per page. page (integer, default: 1) – Page number. format (string, default: json) – Response format (json, xml).
Output	Success: JSON with status, userTier, pagination details, and results array (tags with id, type, webTitle, webUrl). Failure: Error response.
Workflow Example	Execute `getTags?q=politics&api-key=YOUR_KEY`. Retrieve all tags related to politics. Use tags for content categorization and search refinement.

2.3 Sections

Action	getSections
Purpose	Retrieves the available Guardian content sections (e.g., news, sport, culture).
Parameters	Required: api-key (string) – Your API key. Optional: q (string) – Search terms for sections. format (string, default: json) – Response format (json, xml).
Output	Success: JSON with status, userTier, and results array of sections (id, webTitle, webUrl, apiUrl, closed). Failure: Error details.
Workflow Example	Execute `getSections?api-key=YOUR_KEY`. Retrieve all available content sections. Use sections to build navigation menus.

2.4 Editions

Action	getEditions
Purpose	Retrieves the available Guardian editions (UK, US, AU).
Parameters	Required: api-key (string) – Your API key. Optional: q (string) – Search terms for editions. format (string, default: json) – Response format (json, xml).
Output	Success: JSON with status, userTier, and results array of editions (id, webTitle, webUrl, apiUrl). Failure: Error details.
Workflow Example	Execute `getEditions?api-key=YOUR_KEY`. Retrieve UK, US, and AU editions. Use edition filtering for localized news feeds.

2.5 Single Item by ID

Action	getItemById
Purpose	Retrieves details of a specific Guardian content item using its ID.
Parameters	Required: id (string) – Content identifier (path parameter, e.g., uk-news/2023/jan/01/example-article). api-key (string) – Your API key. Optional: show-fields (string) – Comma-separated list of fields (e.g., bodyText, byline). show-tags (string) – Tags to include (contributor, keyword, series, tone). show-refinements (boolean) – Whether to include refinements. show-blocks (string) – Show blocks (body, all). format (string, default: json) – Response format (json, xml).
Output	Success: JSON object with status, userTier, and content (article metadata and body fields, including tags and blocks). Failure: Error response (e.g., invalid ID).
Workflow Example	Execute `getItemById(id="uk-news/2023/jan/01/example-article", api-key=YOUR_KEY)`. Retrieve full details of the specified article. Display the article content with tags and fields.

Workflow Creation with the Connector

Example Workflow: News Feed Application

Search for Articles	Execute `search?q=technology&order-by=newest&api-key=YOUR_KEY`. Retrieve the latest technology articles.
Retrieve Tags for Filtering	Execute `getTags?q=technology&api-key=YOUR_KEY`. Use tags to allow users to refine searches by topic or author.
Retrieve Sections	Execute `getSections?api-key=YOUR_KEY`. Display sections (e.g., World, Sport, Culture) as navigation.
Retrieve Editions	Execute `getEditions?api-key=YOUR_KEY`. Allow users to select UK, US, or AU editions for localized content.
Retrieve Specific Content	Execute `getItemById(id="technology/2023/jan/01/example-article", api-key=YOUR_KEY)`. Display full content with author, publication date, and body text.

Pricing

bill-and-calculator-2023-11-27-05-25-06-utc 1

Request a Quote

Support

For Technical support please contact us on

custom-connectors-support@isolutions.sa

A tech solution company dedicated to providing innovation thus empowering businesses to thrive in the digital age.

Register to Wired for Banking