Struct aletheia::GuardianContentClient

pub struct GuardianContentClient { /* private fields */ }

The main asynchronous client used to build requests to send to the Guardian’s content API. This client maintains a private internal asynchronous client implemented by reqwest::Client

Implementations

impl GuardianContentClient

pub fn new(api_key: &str) -> GuardianContentClient

Constructor for the client. The constructor takes an API key which is then stored internally in the struct. The client then uses the builder pattern to add query parameters to the request. The query-building methods as well as the terminal operation take a mutable borrow of self. This allows the client not to be consumed after a request. As a result, the client should be initialised with the mut keyword.

API keys for the Guardian’s content API can be requested at https://open-platform.theguardian.com/access/

Example

let mut client = aletheia::GuardianContentClient::new("api-key-here");

pub fn endpoint(&mut self, endpoint: Endpoint) -> &mut GuardianContentClient

Specify the Guardian API endpoint to target.

Can be one of:

• Endpoint::Content (default): returns all pieces of content in the API.
• Endpoint::Tags: returns all tags in the API. All Guardian content is manually categorised using these tags, of which there are more than 50,000.
• Endpoint::Sections: returns all sections in the API.
• Endpoint::Editions: returns all editions in the API. Editions are the different front pages of the Guardian site (currently, there are editions for the United Kingdom, the United States and Australia).
• Endpoint::SingleItem: returns all the data for a given single item id. Here the term ‘item’ refers to either a piece of content, a tag, or a section. The item endpoint matches the paths on theguardian.com.

Example 1

let response = client
        .endpoint(Endpoint::Tags)
        .search("food")
        .send()
        .await?;

Example 2

let response = client
        .endpoint(Endpoint::SingleItem)
        .search("books/2022/jan/01/2022-in-books-highlights-for-the-year-ahead")
        .send()
        .await?;

pub fn search(&mut self, q: &str) -> &mut GuardianContentClient

Add a search query to the request.

Supports AND, OR and NOT operators, and exact phrase queries using double quotes. Examples of valid queries:

• “Barack Obama”
• Music
• Programming AND coding

This field is only valid for the following endpoints:

• Endpoint::Content (default endpoint, no need to explicitly set it)
• Endpoint::Tags
• Endpoint::Sections
• Endpoint::Editions

Calling this method on Endpoint::SingleItem will have no effect.

Example

let response = client
        .search("Elections")
        .send()
        .await?;

pub fn page(&mut self, page: u32) -> &mut GuardianContentClient

Add a page number to the request.

Results are returned as a paginated list, with a default of 10 results. In order to page through the results, you can pass the page number as a parameter to this function.

Example

let response = client
        .search("Elections")
        .page(10)
        .send()
        .await?;

pub fn page_size(&mut self, page: u8) -> &mut GuardianContentClient

Attach a page size to the request.

Results are returned as a paginated list, with a default of 10 results. This function overrides the default. The page value must be between 0 and 200 for a successful response.

Example

let response = client
        .search("Elections")
        .page_size(20)
        .send()
        .await?;

pub fn order_by(&mut self, order_by: OrderBy) -> &mut GuardianContentClient

Return results in the specified order.

The function only accepts one of three enums::OrderBy variants:

• OrderBy::Newest
• OrderBy::Oldest
• OrderBy::Relevance

Example

let response = client
        .search("Elections")
        .order_by(OrderBy::Oldest)
        .send()
        .await?;

pub fn order_date(&mut self, order_date: OrderDate) -> &mut GuardianContentClient

Change which type of date is used to order the results

The function only accepts one of three enums::OrderDate variants:

• OrderDate::Published
• OrderDate::NewspaperEdition
• OrderDate::LastModified

Example

let response = client
        .search("Elections")
        .order_by(OrderDate::NewspaperEdition)
        .send()
        .await?;

pub fn show_fields(
    &mut self,
    show_fields: Vec<Field>
) -> &mut GuardianContentClient

Add fields associated with the content.

The function accepts a vector of enums::Field variants, e.g.

• Field::TrailText
• Field::Body
• Field::Byline

If Field::All is included in the vector, it will override all other fields.

See https://open-platform.theguardian.com/documentation/search for more information on all the possible fields, or check the crate::enums section of the documentation.

Example

let response = client
        .search("Elections")
        .show_fields(vec![Field::StarRating, Field::ShortUrl])
        .send()
        .await?;

pub fn show_tags(&mut self, show_tags: Vec<Tag>) -> &mut GuardianContentClient

Add associated metadata tags.

The function accepts a vector of enums::Tag variants, e.g.

• Tag::Blog
• Tag::Contributor
• Tag::Tone

If Tag::All is included in the vector, it will override all other tags.

See https://open-platform.theguardian.com/documentation/search for more information on all the possible tags, or check the crate::enums section of the documentation.

Example

let response = client
        .search("Elections")
        .show_tags(vec![Tag::Contributor, Tag::Type, Tag::Tone])
        .send()
        .await?;

pub fn query_fields(
    &mut self,
    query_fields: Vec<Field>
) -> &mut GuardianContentClient

Specify in which indexed fields query terms should be searched on

The function accepts a vector of enums::Field variants, e.g.

• Field::TrailText
• Field::Body
• Field::Byline

See https://open-platform.theguardian.com/documentation/search for more information on all the possible fields, or check the crate::enums section of the documentation.

Example

let response = client
        .search("Elections")
        .query_fields(vec![Field::Body])
        .send()
        .await?;

pub fn date_from(
    &mut self,
    year: i32,
    month: u32,
    day: u32
) -> &mut GuardianContentClient

Only return content published on or after the specified date.

Example

let response = client
        .search("Elections")
        .date_from(2020, 1, 1)
        .send()
        .await?;

pub fn datetime_from(
    &mut self,
    year: i32,
    month: u32,
    day: u32,
    hour: u32,
    min: u32,
    sec: u32,
    timezone: i32
) -> &mut GuardianContentClient

Only return content published on or after the specified date.

It is more specific than date_from() as it accepts hours, minutes, seconds as well as a timezone offset.

Note: Providing invalid YMD-HMS does not append query parameters to the API request.

Example

let response = client
        .search("Elections")
        .datetime_from(2020, 1, 1, 12, 0, 0, 2)
        .send()
        .await?;

pub fn date_to(
    &mut self,
    year: i32,
    month: u32,
    day: u32
) -> &mut GuardianContentClient

Only return content published on or before the specified date.

Example

let response = client
        .search("Elections")
        .date_from(2008, 1, 1)
        .date_to(2010, 12, 31)
        .send()
        .await?;

pub fn datetime_to(
    &mut self,
    year: i32,
    month: u32,
    day: u32,
    hour: u32,
    min: u32,
    sec: u32,
    timezone: i32
) -> &mut GuardianContentClient

Only return content published on or before the specified date.

It is more specific than date_to() as it accepts hours, minutes, seconds as well as a timezone offset.

Note: Providing invalid YMD-HMS does not append query parameters to the API request.

Example

let response = client
        .search("Elections")
        .datetime_to(2016, 1, 1, 12, 0, 0, 5)
        .send()
        .await?;

pub fn use_date(&mut self, use_date: UseDate) -> &mut GuardianContentClient

Change which type of date is used to filter the results using date_from(), datetime_from(), date_to() and datetime_to().

The function only accepts one of four enums::UseDate variants:

• UseDate::Published (default)
• UseDate::FirstPublication
• UseDate::NewspaperEdition
• UseDate::LastModified

Example

let response = client
        .search("Elections")
        .date_from(2015, 1, 1)
        .date_to(2018, 12, 31)
        .use_date(UseDate::FirstPublication)
        .send()
        .await?;

pub fn show_section(&mut self, show_section: bool) -> &mut GuardianContentClient

Add associated metadata section.

Example

let response = client
        .search("Elections")
        .show_section(true)
        .send()
        .await?;

pub fn section(&mut self, section: &str) -> &mut GuardianContentClient

Return only content in those sections.

Example

let response = client
        .search("Elections")
        .section("football")
        .send()
        .await?;

pub fn reference(&mut self, reference: &str) -> &mut GuardianContentClient

Return only content with those references.

Example

let response = client
        .search("Elections")
        .reference("isbn/9780718178949")
        .send()
        .await?;

pub fn reference_type(
    &mut self,
    reference_type: &str
) -> &mut GuardianContentClient

Return only content with references of those types.

Example

let response = client
        .search("Elections")
        .reference_type("isbn")
        .send()
        .await?;

pub fn tag(&mut self, tag: &str) -> &mut GuardianContentClient

Return only content with those tags.

Example

let response = client
        .search("Elections")
        .tag("technology/apple")
        .send()
        .await?;

pub fn ids(&mut self, ids: &str) -> &mut GuardianContentClient

Return only content with those IDs.

Example

let response = client
        .search("Elections")
        .ids("world/2022/jan/01/funeral-of-desmond-tutu-takes-place-in-cape-town")
        .send()
        .await?;

pub fn production_office(
    &mut self,
    production_office: &str
) -> &mut GuardianContentClient

Return only content from those production offices.

Example

let response = client
        .search("Elections")
        .production_office("UK")
        .send()
        .await?;

pub fn lang(&mut self, lang: &str) -> &mut GuardianContentClient

Return only content in those languages. Accepts ISO language codes, e.g. en, fr.

Example

let response = client
        .search("Elections")
        .lang("en")
        .send()
        .await?;

pub fn star_rating(&mut self, star_rating: u8) -> &mut GuardianContentClient

Return only content with a given star rating ranging from 1 to 5.

Example

let response = client
        .search("Elections")
        .star_rating(5)
        .send()
        .await?;

pub fn tag_type(&mut self, type: &str) -> &mut GuardianContentClient

Only return tags of the specified type. Only valid if the endpoint is set to Endpoint::Tags

Example

let response = client
        .endpoint(Endpoint::Tags)
        .search("Elections")
        .tag_type("tv-and-radio/us-television")
        .send()
        .await?;

pub fn show_blocks(
    &mut self,
    show_blocks: Vec<Block<'_>>
) -> &mut GuardianContentClient

Add associated blocks (single block for content, one or more for liveblogs).

Supports the following enums::Block variants:

• Block::Main
• Block::Body
• Block::All
• Block::BodyLatest (limit defaults to 20)
• [Block::BodyLatestWith(i32)] (override the limits)
• Block::BodyOldest
• [Block::BodyOldestWith(i32)]
• [Block::BodyBlockId(&'a str)] (only the block with that ID)
• [Block::BodyAroundBlockId(&'a str)] (the specified block and 20 blocks either side of it)
• [Block::BodyAroundBlockIdWith(&'a str, i32)] (the specified block and n blocks either side of it)
• Block::BodyKeyEvents
• [Block::BodyPublishedSince(i64)] (only blocks since given timestamp)

Example

let response = client
        .endpoint(Endpoint::Tags)
        .search("Elections")
        .show_blocks(Block::BodyPublishedSince(1556529318000))
        .send()
        .await?;

pub async fn send(&mut self) -> Result<SearchResponse>

Terminal operation that sends a GET request to the Guardian API. Once this function is called, all the query parameters constructed via the building methods are dropped.

Trait Implementations

impl Clone for GuardianContentClient

fn clone(&self) -> GuardianContentClient

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GuardianContentClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.