Zyte API Python Client

Common errors

• RuntimeWarning: coroutine 'request_render' was never awaited

  cause An asynchronous method of `ZyteAPI` was called without being `await`ed within an `async` context.
  fix Ensure that `api.request_render(...)` is preceded by `await` and executed inside an `async` function, which is then run using `asyncio.run()` or similar.

• zyte_api.errors.ZyteAPIError: Authentication failed: Invalid API key or insufficient permissions.

  cause The Zyte API key provided is either missing, incorrect, or does not have the necessary permissions for the requested operation.
  fix Verify that your `ZYTE_API_KEY` environment variable is correctly set or that the `api_key` argument passed to `ZyteAPI` is valid and active.

• TypeError: 'RequestResult' object is not subscriptable

  cause Attempting to access fields of the `RequestResult` object (returned by `ZyteAPI` methods since v0.6.0) using dictionary-like square bracket notation (`result['key']`).
  fix Access the fields using dot notation instead, for example, `result.browserData.title` or `result.httpResponseBody`.

Warnings

• breaking Starting from version 0.6.0, `ZyteAPI` methods (e.g., `request_render`) return a `RequestResult` object instead of a dictionary. Access data using dot notation (e.g., `result.browserData.title`) instead of dictionary-like square brackets (`result['browserData']['title']`).
  Fix: Update your code to use attribute access for `RequestResult` objects, e.g., `result.field_name`.
• gotcha The `ZyteAPI` client is primarily asynchronous. All API request methods (e.g., `request_render`) are coroutines and must be `await`ed within an `async` function. Running directly without `await` will result in `RuntimeWarning: coroutine was never awaited`.
  Fix: Wrap your API calls in an `async` function and use `await` for each call. Execute the main `async` function using `asyncio.run()`.
• gotcha The Zyte API key is mandatory for authentication. It must be provided either via the `ZYTE_API_KEY` environment variable or passed directly to the `ZyteAPI` constructor as the `api_key` argument. Failure to do so will result in authentication errors.
  Fix: Ensure `os.environ['ZYTE_API_KEY']` is set with your valid Zyte API key, or instantiate the client as `api = ZyteAPI(api_key='YOUR_KEY')`.
• breaking Support for Python 3.7 was dropped in version 0.7.0. If you are using Python 3.7, you must either upgrade your Python version to 3.8 or higher, or pin your `zyte-api` dependency to a version less than 0.7.0 (e.g., `zyte-api<0.7.0`).
  Fix: Upgrade your Python environment to 3.8 or newer, or specify `zyte-api<0.7.0` in your `requirements.txt`.

Install

• pip install zyte-api Install `zyte-api`

Imports

• ZyteAPI

  from zyte_api.zyte_api import ZyteAPI

• ZyteAPIError

  from zyte_api.errors import ZyteAPIError

Quickstart

This quickstart demonstrates how to initialize the `ZyteAPI` client with an API key (preferably from an environment variable) and make an asynchronous `request_render` call to fetch HTML, a screenshot, and page data for a given URL. It uses `asyncio.run()` to execute the asynchronous operation.

import os
import asyncio
from zyte_api.zyte_api import ZyteAPI

api_key = os.environ.get('ZYTE_API_KEY', '') # Set ZYTE_API_KEY environment variable or replace with your key

async def main():
    if not api_key:
        print("ZYTE_API_KEY environment variable not set. Skipping quickstart example.")
        return

    api = ZyteAPI(api_key=api_key)
    try:
        print("Making a request to Zyte API for www.zyte.com...")
        result = await api.request_render(
            url="https://www.zyte.com/",
            browserHtml=True,
            screenshot=True,
            httpResponseBody=True,
            javascript=True
        )

        print(f"Request Status: {result.status}")
        if result.browserData:
            print(f"Page title: {result.browserData.title}")
        if result.browserHtml:
            print(f"HTML (first 100 chars): {result.browserHtml[:100]}...")
        if result.screenshot:
            print(f"Screenshot (base64, first 50 chars): {result.screenshot[:50]}...")
        print("Successfully received Zyte API response.")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == '__main__':
    asyncio.run(main())