Skip to content

Simplify overview page #646

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
patrikbraborec wants to merge 1 commit into from
Closed

Simplify overview page #646

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 13 additions & 114 deletions docs/01_overview/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,90 +7,37 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';

import AuthAsyncExample from '!!raw-loader!./code/02_auth_async.py';
import AuthSyncExample from '!!raw-loader!./code/02_auth_sync.py';
import UsageAsyncExample from '!!raw-loader!./code/01_usage_async.py';
import UsageSyncExample from '!!raw-loader!./code/01_usage_sync.py';
import InputAsyncExample from '!!raw-loader!./code/03_input_async.py';
import InputSyncExample from '!!raw-loader!./code/03_input_sync.py';
import DatasetAsyncExample from '!!raw-loader!./code/03_dataset_async.py';
import DatasetSyncExample from '!!raw-loader!./code/03_dataset_sync.py';

## Introduction
The Apify API client for Python is the official library to access the [Apify REST API](/api/v2) from your Python applications. It provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API.

The [Apify client for Python](https://github.com/apify/apify-client-python) is the official library to access the [Apify REST API](/api/v2) from your Python applications. It provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API.
The client simplifies interaction with the Apify platform by providing:

Key features:

- Synchronous and asynchronous interfaces for flexible integration
- Automatic retries for improved reliability
- JSON encoding with UTF-8 for all requests and responses
- Comprehensive API coverage for [Actors](/platform/actors), [datasets](/platform/storage/dataset), [key-value stores](/platform/storage/key-value-store), and more
- Intuitive methods for working with [Actors](/platform/actors), [datasets](/platform/storage/dataset), [key-value stores](/platform/storage/key-value-store), and other Apify resources
- Both synchronous and asynchronous interfaces for flexible integration
- Built-in [retries with exponential backoff](../02_concepts/05_retries.mdx) for failed requests
- Comprehensive API coverage with JSON encoding (UTF-8) for all requests and responses

## Prerequisites

Before installing the Apify client, ensure your system meets the following requirements:

- _An Apify account_
- _Python 3.11 or higher_: You can download Python from the [official website](https://www.python.org/downloads/).
- _Python package manager_: While this guide uses [pip](https://pip.pypa.io/en/stable/), you can also use any package manager you want.
`apify-client` requires Python 3.11 or higher. Python is available for download on the [official website](https://www.python.org/downloads/). Check your current Python version by running:

To verify that Python and pip are installed, run the following commands:

```sh
```bash
python --version
```

```sh
pip --version
```

If these commands return the respective versions, you're ready to continue.

## Installation

The Apify client is available as the [`apify-client`](https://pypi.org/project/apify-client/) package on PyPI. To install it, run:
The Apify client is available as the [`apify-client`](https://pypi.org/project/apify-client/) package on PyPI.

```sh
```bash
pip install apify-client
```

After installation, verify that the client is installed correctly by checking its version:

```sh
python -c 'import apify_client; print(apify_client.__version__)'
```
## Quick example

## Authentication and initialization

To use the client, you need an [API token](/platform/integrations/api#api-token). You can find your token under the [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing it as a parameter to the `ApifyClient` constructor.

<Tabs>
<TabItem value="AsyncExample" label="Async client" default>
<CodeBlock className="language-python">
{AuthAsyncExample}
</CodeBlock>
</TabItem>
<TabItem value="SyncExample" label="Sync client">
<CodeBlock className="language-python">
{AuthSyncExample}
</CodeBlock>
</TabItem>
</Tabs>

:::warning Secure access

The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications.

:::

## Quick start

Now that you have the client set up, let's explore how to run Actors on the Apify platform, provide input to them, and retrieve their results.

### Running your first Actor

To start an Actor, you need its ID (e.g., `john-doe/my-cool-actor`) and an API token. The Actor's ID is a combination of the Actor name and the Actor owner's username. Use the [`ActorClient`](/reference/class/ActorClient) to run the Actor and wait for it to complete. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store).
Here's an example showing how to run an Actor and retrieve its results:

<Tabs>
<TabItem value="AsyncExample" label="Async client" default>
Expand All @@ -105,52 +52,4 @@ To start an Actor, you need its ID (e.g., `john-doe/my-cool-actor`) and an API t
</TabItem>
</Tabs>

### Providing input to Actor

Actors often require input, such as URLs to scrape, search terms, or other configuration data. You can pass input as a JSON object when starting the Actor using the [`ActorClient.call`](/reference/class/ActorClient#call) method. Actors respect the input schema defined in the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema).

<Tabs>
<TabItem value="AsyncExample" label="Async client" default>
<CodeBlock className="language-python">
{InputAsyncExample}
</CodeBlock>
</TabItem>
<TabItem value="SyncExample" label="Sync client">
<CodeBlock className="language-python">
{InputSyncExample}
</CodeBlock>
</TabItem>
</Tabs>

### Getting results from the dataset

To get the results from the dataset, you can use the [`DatasetClient`](/reference/class/DatasetClient) ([`ApifyClient.dataset`](/reference/class/ApifyClient#dataset)) and [`DatasetClient.list_items`](/reference/class/DatasetClient#list_items) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run dictionary (represented by `defaultDatasetId`).

<Tabs>
<TabItem value="AsyncExample" label="Async client" default>
<CodeBlock className="language-python">
{DatasetAsyncExample}
</CodeBlock>
</TabItem>
<TabItem value="SyncExample" label="Sync client">
<CodeBlock className="language-python">
{DatasetSyncExample}
</CodeBlock>
</TabItem>
</Tabs>

:::note Dataset access

Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response, you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs).

:::

## Next steps

Now that you're familiar with the basics, explore more advanced features:

- [Asyncio support](/concepts/asyncio-support) - Learn about asynchronous programming with the client
- Common use-case examples like:
- [Passing an input to Actor](/api/client/python/docs/examples/passing-input-to-actor)
- [Retrieve Actor data](/api/client/python/docs/examples/retrieve-actor-data)
- [API Reference](/api/client/python/reference) - Browse the complete API documentation
> You can find your API token in the [Integrations section](https://console.apify.com/account/integrations) of Apify Console.
Loading