Getting started overview

Integrating with The Guardian Content API requires obtaining an API key and constructing URL-based queries. The process typically begins with account creation on The Guardian's Open Platform, followed by key generation. Once a key is acquired, it is included in API requests as a query parameter. The API serves content in JSON format, facilitating programmatic parsing and display Guardian Content API documentation.

This guide provides a step-by-step approach to initiate development with The Guardian Content API, covering account registration, API key retrieval, and executing a foundational request. Adherence to best practices for API key management and request construction is recommended to ensure secure and efficient data access.

Quick Reference Guide

Step What to Do Where
1. Register Create a new developer account. Guardian Open Platform API reference
2. Get Key Generate your unique API key. Guardian Open Platform Dashboard (after registration)
3. Make Request Construct and execute your first API call. Command line (cURL), browser, or programming environment
4. Parse Data Process the JSON response. Your application code

Create an account and get keys

To begin using The Guardian Content API, developers must first register for an account on The Guardian's Open Platform. This registration process is distinct from a standard Guardian reader account and is specifically designed for API access.

  1. Navigate to the Open Platform: Visit The Guardian's Open Platform documentation page.

  2. Register for an account: Locate the registration link, typically labeled "Register for an API key" or similar. Provide the requested information, which commonly includes an email address and a password. Some platforms may require agreeing to terms of service before proceeding with account creation.

  3. Activate your account: After submitting registration details, check your email for a verification link. Clicking this link typically activates your developer account.

  4. Generate your API key: Once logged into your developer dashboard, there will be an option to generate an API key. This key is a unique string that identifies your application and authorizes your API requests. It is crucial to keep this key confidential, as unauthorized use of your API key could impact your daily request quota or incur charges if operating on a paid tier. The Guardian's free tier allows up to 5,000 requests per day Guardian API usage limits.

  5. Store your API key securely: API keys should never be hardcoded directly into client-side applications. For server-side applications, store the key as an environment variable or in a secure configuration management system. Best practices for API key security are detailed by organizations like the Open Web Application Security Project (OWASP) OWASP Top Ten Web Application Security Risks.

Your first request

After acquiring your API key, you can make your inaugural request to The Guardian Content API. This example demonstrates fetching recent articles using a simple HTTP GET request.

Request Structure

The Guardian Content API uses a base URL, followed by an endpoint, and then query parameters, including your API key.

GET https://content.guardianapis.com/search?api-key=YOUR_API_KEY_HERE

Replace YOUR_API_KEY_HERE with the actual API key obtained from your developer dashboard.

Example: Fetching recent articles (cURL)

The curl command-line tool is a common method for testing API endpoints.

curl "https://content.guardianapis.com/search?api-key=YOUR_API_KEY_HERE"

This command will perform a basic search, returning a default set of recent articles. To demonstrate fetching content in a more structured way, consider adding parameters:

curl "https://content.guardianapis.com/search?q=ukraine%20war&format=json&show-fields=headline,thumbnail&api-key=YOUR_API_KEY_HERE"

This enhanced request searches for articles related to "ukraine war", specifies JSON format, and requests specific fields (headline, thumbnail) for each article. URL encoding for query parameters like q=ukraine%20war is standard practice for web requests MDN web docs on URL encoding.

Expected Response (excerpt)

A successful response will return a JSON object containing the requested content. The structure typically includes a response object with a results array.

{
  "response": {
    "status": "ok",
    "userTier": "developer",
    "total": 12345,
    "startIndex": 1,
    "pageSize": 10,
    "currentPage": 1,
    "pages": 1235,
    "orderBy": "newest",
    "results": [
      {
        "id": "world/2026/may/29/example-article-title-1",
        "type": "article",
        "sectionId": "world",
        "sectionName": "World news",
        "webPublicationDate": "2026-05-29T10:00:00Z",
        "webTitle": "Example Article Title One",
        "webUrl": "https://www.theguardian.com/world/2026/may/29/example-article-title-1",
        "apiUrl": "https://content.guardianapis.com/world/2026/may/29/example-article-title-1",
        "fields": {
          "headline": "Example Article Title One",
          "thumbnail": "https://assets.guim.co.uk/img/media/example-thumbnail-1.jpg"
        },
        "isHosted": false,
        "pillarId": "pillar/news",
        "pillarName": "News"
      }
      // ... more results
    ]
  }
}

This JSON structure allows developers to extract relevant information such as article titles, publication dates, and URLs for display or further processing. The fields object contains the specific fields requested via the show-fields parameter.

Common next steps

After successfully making your first API call, consider these next steps to enhance your integration:

  • Explore additional parameters: The Guardian Content API offers numerous query parameters for filtering, sorting, and refining searches. Review the API reference documentation to understand options like page-size, from-date, to-date, section, and tag. These parameters enable precise content retrieval.

  • Handle pagination: For queries returning large datasets, implement pagination using the page and page-size parameters to retrieve results incrementally. This prevents overwhelming your application and adheres to API best practices.

  • Error handling: Implement robust error handling in your application to gracefully manage scenarios such as invalid API keys, rate limit breaches, or malformed requests. The API typically returns HTTP status codes (e.g., 401 for unauthorized, 429 for rate limited) and descriptive error messages in the JSON response.

  • Integrate into a programming language: Move beyond cURL by integrating API calls into your preferred programming language (e.g., Python with requests, JavaScript with fetch, Java with HttpClient). This allows for dynamic request construction and seamless data processing within your application logic.

  • Cache responses: To reduce redundant API calls and stay within your daily quota, consider implementing a caching strategy for frequently accessed data. Storing API responses locally for a defined period can improve application performance and reduce load on the API.

  • Understand rate limits: Be aware of the free tier's 5,000 requests per day limit. For applications requiring higher volumes, investigate enterprise access options or consider strategies to optimize API usage.

  • Stay updated: Regularly check The Guardian's Open Platform documentation for updates, new features, or deprecations that might affect your integration.

Troubleshooting the first call

When your initial API request doesn't return the expected results, several common issues can be addressed:

  • Invalid API Key: Double-check that the API key in your request URL exactly matches the key generated in your developer dashboard. Even a single character mismatch will result in an authentication error, typically an HTTP 401 Unauthorized status code.

  • Incorrect URL or Endpoint: Verify the base URL (https://content.guardianapis.com/) and the specific endpoint (e.g., /search) are correct. Refer to the Guardian Content API reference for exact endpoint paths and available parameters. A common mistake is typos in endpoint names.

  • Missing or Malformed Parameters: Ensure all required query parameters are present and correctly formatted. For instance, if you're searching for a specific query, ensure q=your_query is properly URL-encoded (e.g., spaces replaced with %20). Missing the api-key parameter will always result in an error.

  • Network Connectivity Issues: Confirm your development environment has stable internet access and is not blocked by a firewall or proxy that would prevent outbound HTTP requests to content.guardianapis.com.

  • Rate Limiting: While less likely on a very first call unless you've made many attempts quickly, subsequent calls might hit the daily limit for the free tier (5,000 requests per day). If you receive an HTTP 429 Too Many Requests status, you have exceeded your quota. Wait for the reset period or contact The Guardian for enterprise access if higher volumes are needed.

  • JSON Parsing Errors: If the API returns a response but your application fails to process it, the issue might be with your JSON parsing logic. Use online JSON validators or debugging tools in your IDE to inspect the raw JSON response and ensure your code correctly handles its structure.

  • Checking HTTP Status Codes: Always inspect the HTTP status code returned with the API response. Codes like 200 (OK) indicate success, while 4xx codes (Client Error) and 5xx codes (Server Error) point to specific problems. The IETF RFC 7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content defines these status codes.