openapi: 3.0.3
info:
  title: The Guardian Content API
  description: The Guardian's Open Platform Content API provides free access to all content published on theguardian.com. Search for articles, browse sections and tags, retrieve specific content items, and access edition-specific content. Supports filtering by date, section, tag, and more.
  version: 2.0.0
  contact:
    name: The Guardian Open Platform
    url: https://open-platform.theguardian.com/
  termsOfService: https://open-platform.theguardian.com/access/
  x-jentic-source-url: https://open-platform.theguardian.com/
servers:
- url: https://content.guardianapis.com
  description: Guardian Content API Production Server
security:
- apiKeyQuery: []
tags:
- name: Content
  description: Search and retrieve Guardian content items
paths:
  /search:
    get:
      operationId: searchContent
      summary: Search for content
      description: Search all Guardian content. Returns articles, liveblogs, galleries, and other content types matching the query. Results are paginated and can be filtered by section, tag, date range, and more.
      tags:
      - Content
      parameters:
      - name: q
        in: query
        description: Full-text search query. Supports AND, OR, NOT operators.
        schema:
          type: string
      - name: query-fields
        in: query
        description: Specify which indexed fields are used by the q parameter (e.g., headline, body, all)
        schema:
          type: string
      - name: section
        in: query
        description: Filter by section ID (e.g., technology, sport). Use | for OR, - prefix to exclude.
        schema:
          type: string
      - name: tag
        in: query
        description: Filter by tag ID (e.g., technology/apple). Use comma for AND, | for OR, - to exclude.
        schema:
          type: string
      - name: type
        in: query
        description: Filter by content type
        schema:
          type: string
          enum:
          - article
          - liveblog
          - gallery
          - interactive
          - picture
          - video
          - crossword
          - audio
      - name: from-date
        in: query
        description: Return content published on or after this date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: to-date
        in: query
        description: Return content published on or before this date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: order-by
        in: query
        description: Sort order for results
        schema:
          type: string
          enum:
          - newest
          - oldest
          - relevance
          default: relevance
      - name: show-fields
        in: query
        description: Comma-separated list of article fields to include (e.g., body,headline,thumbnail,shortUrl,byline,trailText,wordcount,starRating,all)
        schema:
          type: string
      - name: show-tags
        in: query
        description: Comma-separated list of tag types to include (e.g., keyword,contributor,series,blog,tone,type,all)
        schema:
          type: string
      - name: show-elements
        in: query
        description: Include media elements (image, video, audio, all)
        schema:
          type: string
      - name: show-blocks
        in: query
        description: Include block-level content (body, all, main)
        schema:
          type: string
      - name: show-references
        in: query
        description: Include references
        schema:
          type: string
      - name: page
        in: query
        description: Page number for pagination
        schema:
          type: integer
          default: 1
      - name: page-size
        in: query
        description: Number of results per page (max 50 for free tier)
        schema:
          type: integer
          default: 10
          maximum: 200
      - name: use-date
        in: query
        description: Which date to use for filtering and ordering
        schema:
          type: string
          enum:
          - published
          - first-publication
          - newspaper-edition
          - last-modified
      - name: lang
        in: query
        description: ISO language code to filter content by language
        schema:
          type: string
      - name: star-rating
        in: query
        description: Filter by star rating (for reviews)
        schema:
          type: integer
          minimum: 1
          maximum: 5
      - name: production-office
        in: query
        description: Filter by production office
        schema:
          type: string
          enum:
          - uk
          - us
          - aus
      responses:
        '200':
          description: Successful response with search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{contentId}:
    get:
      operationId: getItem
      summary: Get a single content item
      description: Retrieve a specific content item by its ID path (e.g., technology/2024/jan/01/article-slug).
      tags:
      - Content
      parameters:
      - name: contentId
        in: path
        required: true
        description: The ID (path) of the content item (e.g., world/2024/jan/01/article-slug)
        schema:
          type: string
      - name: show-fields
        in: query
        description: Comma-separated list of fields to include
        schema:
          type: string
      - name: show-tags
        in: query
        description: Comma-separated list of tag types to include
        schema:
          type: string
      - name: show-elements
        in: query
        description: Include media elements
        schema:
          type: string
      - name: show-blocks
        in: query
        description: Include block-level content
        schema:
          type: string
      - name: show-references
        in: query
        description: Include references
        schema:
          type: string
      responses:
        '200':
          description: Successful response with content item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResponse'
        '404':
          description: Content item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SearchResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            status:
              type: string
              description: Response status
              enum:
              - ok
              - error
            userTier:
              type: string
              description: API access tier
              enum:
              - developer
              - partner
              - internal
            total:
              type: integer
              description: Total number of results
            startIndex:
              type: integer
              description: Starting index of results
            pageSize:
              type: integer
              description: Number of results per page
            currentPage:
              type: integer
              description: Current page number
            pages:
              type: integer
              description: Total number of pages
            orderBy:
              type: string
              description: Sort order of results
            results:
              type: array
              items:
                $ref: '#/components/schemas/ContentItem'
    Tag:
      type: object
      properties:
        id:
          type: string
          description: Tag identifier
        type:
          type: string
          description: Tag type
          enum:
          - keyword
          - series
          - contributor
          - blog
          - tone
          - type
          - newspaper-book
          - newspaper-book-section
        sectionId:
          type: string
        sectionName:
          type: string
        webTitle:
          type: string
        webUrl:
          type: string
          format: uri
        apiUrl:
          type: string
          format: uri
        keywordType:
          type: string
    ErrorResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            status:
              type: string
              enum:
              - error
            message:
              type: string
              description: Error message
    ItemResponse:
      type: object
      properties:
        response:
          type: object
          properties:
            status:
              type: string
            userTier:
              type: string
            total:
              type: integer
            content:
              $ref: '#/components/schemas/ContentItem'
    ContentItem:
      type: object
      properties:
        id:
          type: string
          description: Unique content identifier path
        type:
          type: string
          description: Content type
          enum:
          - article
          - liveblog
          - gallery
          - interactive
          - picture
          - video
          - crossword
          - audio
        sectionId:
          type: string
          description: Section identifier
        sectionName:
          type: string
          description: Human-readable section name
        webPublicationDate:
          type: string
          format: date-time
          description: Publication date in ISO 8601 format
        webTitle:
          type: string
          description: Article headline
        webUrl:
          type: string
          format: uri
          description: URL on theguardian.com
        apiUrl:
          type: string
          format: uri
          description: API URL for this content item
        isHosted:
          type: boolean
          description: Whether the content is hosted by the Guardian
        pillarId:
          type: string
          description: Content pillar identifier
        pillarName:
          type: string
          description: Content pillar name
        fields:
          type: object
          description: Additional fields (when show-fields is specified)
          properties:
            headline:
              type: string
            body:
              type: string
            thumbnail:
              type: string
            shortUrl:
              type: string
            byline:
              type: string
            trailText:
              type: string
            wordcount:
              type: string
            starRating:
              type: string
            standfirst:
              type: string
            lastModified:
              type: string
            publication:
              type: string
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api-key
      description: API key obtained from https://open-platform.theguardian.com/access/. A test key 'test' is available for development.