{
  "openapi": "3.0.1",
  "info": {
    "title": "Guardian Articles & Liveblogs Scraper",
    "description": "Fetches Guardian articles and liveblogs via the Guardian's own Open Platform Content API -- headline, standfirst, full body text, byline, contributor and keyword tags, section and dates -- with search, section, tag and date filtering across 1.9M+ items. Needs your own free Guardian API key.",
    "version": "0.1",
    "x-build-id": "jZYvD5uDBb2xMV8aT"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapyx~guardian-articles-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapyx-guardian-articles-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/scrapyx~guardian-articles-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapyx-guardian-articles-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/scrapyx~guardian-articles-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapyx-guardian-articles-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "apiKey"
        ],
        "properties": {
          "apiKey": {
            "title": "Guardian API key (required)",
            "type": "string",
            "description": "Your Guardian Open Platform key. Register a free Developer key in about 30 seconds at https://open-platform.theguardian.com/access/ and it is emailed to you. The Developer tier is FREE but NON-COMMERCIAL (1 call/second, 500 calls/day, includes full article text). Commercial use -- including reselling this data or publishing derived products -- needs a Commercial key from the same page. This actor reads the Guardian's own API rather than scraping theguardian.com, which their robots.txt and license.xml do not permit."
          },
          "queries": {
            "title": "Search terms",
            "type": "array",
            "description": "Optional free-text search. Each term is a separate query with its own SEARCH_SUMMARY row and its own share of your daily call budget. Leave empty to search by filters alone -- a section, tag or date range with no keyword is a complete query on this API.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "contentTypes": {
            "title": "Content types",
            "type": "array",
            "description": "Articles, liveblogs, or both in one run. They share an identical schema on this API -- a liveblog is a content item with type 'liveblog' plus a block-by-block update list -- which is why one actor covers both. The API also serves video, gallery, audio, interactive and crossword; those are out of scope for this actor by design.",
            "items": {
              "type": "string",
              "enum": [
                "article",
                "liveblog"
              ],
              "enumTitles": [
                "Articles",
                "Liveblogs"
              ]
            },
            "default": [
              "article"
            ]
          },
          "sections": {
            "title": "Sections",
            "type": "array",
            "description": "Optional Guardian section IDs, e.g. world, politics, business, technology, sport, environment, football, culture. Several values are combined as OR in ONE upstream call rather than one call each, which matters against a 500-call daily budget.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "tags": {
            "title": "Tags",
            "type": "array",
            "description": "Optional Guardian tag IDs, e.g. environment/climate-crisis, technology/artificialintelligenceai, profile/george-monbiot. Tags are the Guardian's richest filter -- every article carries contributor, keyword, tone and series tags. Combined as OR in one call, same as sections.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "dateFrom": {
            "title": "Published from (YYYY-MM-DD)",
            "type": "string",
            "description": "Optional lower bound on publication date, inclusive. Applied upstream by the API, not locally, so it narrows the result set rather than filtering rows after the fact."
          },
          "dateTo": {
            "title": "Published to (YYYY-MM-DD)",
            "type": "string",
            "description": "Optional upper bound on publication date, inclusive."
          },
          "orderBy": {
            "title": "Sort order",
            "enum": [
              "newest",
              "oldest",
              "relevance"
            ],
            "type": "string",
            "description": "Newest first, oldest first, or by the API's own relevance score. Relevance is only meaningful when a search term is supplied.",
            "default": "newest"
          },
          "includeBody": {
            "title": "Include full article text",
            "type": "boolean",
            "description": "Request the complete article body as plain text, plus standfirst, byline and word count. On by default -- full text is the main reason to use this API and the Developer tier includes it. Turning it off makes responses much smaller but costs the same number of API calls.",
            "default": true
          },
          "includeLiveblogUpdates": {
            "title": "Include liveblog updates",
            "type": "boolean",
            "description": "For liveblogs, also return the block-by-block timeline: each update's title, text, publish time and contributors. Off by default because a long liveblog's update list dwarfs the article payload. Has no effect unless 'liveblog' is in Content types.",
            "default": false
          },
          "maxItemsPerQuery": {
            "title": "Max items per query",
            "minimum": 0,
            "type": "integer",
            "description": "Cap on items returned per search term. Set to 0 for everything the query matches -- but note that at 50 items per call, 10,000 items is 200 of your 500 daily calls.",
            "default": 50
          },
          "pageSize": {
            "title": "Items per API call",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many items each upstream call fetches, up to the API maximum of 200. Higher means fewer calls for the same data, which directly conserves your daily quota; the trade-off is a larger response per call.",
            "default": 50
          },
          "maxConcurrency": {
            "title": "Max concurrent requests",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "Leave at 1 on a Developer key. That tier allows one call per second, so concurrency buys nothing and only produces rate-limit errors faster. Raise it only on a Commercial key with a higher throttle.",
            "default": 1
          },
          "minRequestInterval": {
            "title": "Min seconds between API calls",
            "minimum": 0,
            "type": "number",
            "description": "Pacing floor between call starts. The default sits just above the Developer tier's one-call-per-second limit; a start exactly on the second boundary can still land inside the previous second at the server. Lower it only on a Commercial key.",
            "default": 1.1
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "There is no bot mitigation on this endpoint -- it is the Guardian's own developer API and answers plain JSON to any client with a valid key. Residential is the portfolio default; datacentre would work equally well here.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}