# OpenDataSoft Explore Extractor (`datamule/opendatasoft-explore-extractor`) Actor

Point at ANY OpenDataSoft portal (Paris, RTE, data.opendatasoft.com + thousands more) and pull real ROW data via the Explore API v2.1. List the dataset catalog or extract records with ODSQL where/select/order\_by/group\_by + facets. Auto-paginates to flat rows + geo. Pay per record.

- **URL**: https://apify.com/datamule/opendatasoft-explore-extractor.md
- **Developed by:** [Datamule](https://apify.com/datamule) (community)
- **Categories:** Developer tools, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### Scrape single-page in Python template

A template for [web scraping](https://apify.com/web-scraping) data from a single web page in Python. The URL of the web page is passed in via input, which is defined by the [input schema](https://docs.apify.com/platform/actors/development/input-schema). The template uses the [HTTPX](https://www.python-httpx.org) to get the HTML of the page and the [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/) to parse the data from it. The data are then stored in a [dataset](https://docs.apify.com/sdk/python/docs/concepts/storages#working-with-datasets) where you can easily access them.

The scraped data in this template are page headings but you can easily edit the code to scrape whatever you want from the page.

### Included features

- **[Apify SDK](https://docs.apify.com/sdk/python/)** for Python - a toolkit for building Apify [Actors](https://apify.com/actors) and scrapers in Python
- **[Input schema](https://docs.apify.com/platform/actors/development/input-schema)** - define and easily validate a schema for your Actor's input
- **[Request queue](https://docs.apify.com/sdk/python/docs/concepts/storages#working-with-request-queues)** - queues into which you can put the URLs you want to scrape
- **[Dataset](https://docs.apify.com/sdk/python/docs/concepts/storages#working-with-datasets)** - store structured data where each object stored has the same attributes
- **[HTTPX](https://www.python-httpx.org)** - library for making asynchronous HTTP requests in Python
- **[Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/)** - library for pulling data out of HTML and XML files

### How it works

1. `Actor.get_input()` gets the input where the page URL is defined
2. `httpx.AsyncClient().get(url)` fetches the page
3. `BeautifulSoup(response.content, 'lxml')` loads the page data and enables parsing the headings
4. This parses the headings from the page and here you can edit the code to parse whatever you need from the page
   ```python
   for heading in soup.find_all(["h1", "h2", "h3", "h4", "h5", "h6"]):
   ```
5. `Actor.push_data(headings)` stores the headings in the dataset

### Resources

- [BeautifulSoup Scraper](https://apify.com/apify/beautifulsoup-scraper)
- [Python tutorials in Academy](https://docs.apify.com/academy/python)
- [Web scraping with Beautiful Soup and Requests](https://blog.apify.com/web-scraping-with-beautiful-soup/)
- [Beautiful Soup vs. Scrapy for web scraping](https://blog.apify.com/beautiful-soup-vs-scrapy-web-scraping/)
- [Integration with Make, GitHub, Zapier, Google Drive, and other apps](https://apify.com/integrations)
- [Video guide on getting scraped data using Apify API](https://www.youtube.com/watch?v=ViYYDHSBAKM)
- A short guide on how to build web scrapers using code templates:

[web scraper template](https://www.youtube.com/watch?v=u-i-Korzf8w)

### Getting started

For complete information [see this article](https://docs.apify.com/platform/actors/development#build-actor-locally). To run the Actor use the following command:

```bash
apify run
```

### Deploy to Apify

#### Connect Git repository to Apify

If you've created a Git repository for the project, you can easily connect to Apify:

1. Go to [Actor creation page](https://console.apify.com/actors/new)
2. Click on **Link Git Repository** button

#### Push project on your local machine to Apify

You can also deploy the project on your local machine to Apify without the need for the Git repository.

1. Log in to Apify. You will need to provide your [Apify API Token](https://console.apify.com/account/integrations) to complete this action.

   ```bash
   apify login
   ```

2. Deploy your Actor. This command will deploy and build the Actor on the Apify Platform. You can find your newly created Actor under [Actors -> My Actors](https://console.apify.com/actors?tab=my).

   ```bash
   apify push
   ```

### Documentation reference

To learn more about Apify and Actors, take a look at the following resources:

- [Apify SDK for JavaScript documentation](https://docs.apify.com/sdk/js)
- [Apify SDK for Python documentation](https://docs.apify.com/sdk/python)
- [Apify Platform documentation](https://docs.apify.com/platform)
- [Join our developer community on Discord](https://discord.com/invite/jyEM2PRvMU)

# Actor input Schema

## `portalUrl` (type: `string`):

The base URL of ANY OpenDataSoft open-data portal (the platform behind thousands of city/energy/transport/government/corporate data portals). Examples: https://opendata.paris.fr (City of Paris), https://opendata.reseaux-energies.fr (RTE, France's TSO), https://data.opendatasoft.com (the ODS flagship, 90k+ datasets). Just the portal root — do NOT include /api/explore/...; the actor appends it.

## `mode` (type: `string`):

catalog = list the datasets published on the portal. records = pull the actual ROW data of one dataset (requires Dataset id). auto (default) = records when a Dataset id is set, else catalog.

## `datasetId` (type: `string`):

The dataset\_id to pull records from, e.g. les-arbres (opendata.paris.fr) or eco2mix-national-tr (opendata.reseaux-energies.fr). Required for records mode. Run catalog mode first to discover the dataset ids available on a portal.

## `where` (type: `string`):

Optional ODSQL predicate to filter rows (records) or datasets (catalog). Examples (records): hauteurenm > 20; arrondissement = "PARIS 5E ARRDT"; libellefrancais LIKE "Ch\u00eane". Examples (catalog): records\_count > 1000. Full ODSQL: field comparisons, AND/OR/NOT, LIKE, IN, date/geo functions. Leave empty for no filter.

## `select` (type: `string`):

Optional ODSQL select clause — choose/rename columns or compute aggregates. Examples: libellefrancais, hauteurenm; count(\*) as n; avg(hauteurenm) as moy. Leave empty to return every field of each record.

## `groupBy` (type: `string`):

Optional ODSQL group\_by — turns the run into an aggregation (one output row per group). Pair with an aggregate in Select (e.g. group\_by=arrondissement, select=count(\*) as n gives per-arrondissement counts). Records mode only. Leave empty for raw rows.

## `orderBy` (type: `string`):

Optional ODSQL order\_by clause. Examples: hauteurenm DESC; modified DESC; random(). Sorting also lets you page a deeper, deterministic slice of a large dataset (the platform caps paging at offset+limit \u2264 10000). Leave empty for the server's default order.

## `refine` (type: `array`):

Optional facet refinements as facet:value, keeping ONLY rows/datasets matching that facet value. Example (records): domanialite:Alignement. Example (catalog): theme:Environnement. Accepts multiple (ANDed). Leave empty for none.

## `exclude` (type: `array`):

Optional facet exclusions as facet:value, dropping rows/datasets matching that facet value (the inverse of Refine). Example: stadedeveloppement:Jeune. Accepts multiple. Leave empty for none.

## `maxRecords` (type: `integer`):

Maximum total rows to pull across all pages (the actor auto-paginates by offset). Each emitted row is one billable event. The OpenDataSoft API hard-caps paging at offset+limit \u2264 10000, so a single run reaches at most 10000 rows of a dataset \u2014 use a where filter / order\_by to reach deeper slices. Default 1000.

## `limit` (type: `integer`):

Rows requested per API call (the actor auto-follows offset pagination regardless). OpenDataSoft caps this at 100 per call; higher values are clamped. Leave at the default unless you have a reason to change it.

## `lang` (type: `string`):

Optional ODS lang code (e.g. fr, en) used to localize labels and interpret some ODSQL functions. Leave empty for the portal default.

## `timezone` (type: `string`):

Optional IANA timezone (e.g. Europe/Paris, UTC) applied to datetime fields and ODSQL date functions. Leave empty for the portal default (usually UTC).

## `queryParams` (type: `object`):

Arbitrary extra query-string parameters appended to each request, as a JSON object \u2014 the generic passthrough for provider-specific ODS keys not covered above. The reserved keys limit/offset/where/select/order\_by/group\_by/refine/exclude/lang/timezone are managed by the actor and ignored here. Leave empty for none.

## `apikey` (type: `string`):

Optional OpenDataSoft API key for private/key-gated portals or higher rate limits. Sent as Authorization: Apikey \*\*\* \u2014 NOT required for public portals \u2014 leave empty. Never logged.

## `extraHeaders` (type: `object`):

Optional extra HTTP headers to send with every request, as a JSON object. Leave empty for public portals.

## Actor input object example

```json
{
  "portalUrl": "https://opendata.paris.fr",
  "mode": "auto",
  "datasetId": "les-arbres",
  "maxRecords": 1000,
  "limit": 100
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "portalUrl": "https://opendata.paris.fr",
    "datasetId": "les-arbres",
    "maxRecords": 1000,
    "limit": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("datamule/opendatasoft-explore-extractor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "portalUrl": "https://opendata.paris.fr",
    "datasetId": "les-arbres",
    "maxRecords": 1000,
    "limit": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("datamule/opendatasoft-explore-extractor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "portalUrl": "https://opendata.paris.fr",
  "datasetId": "les-arbres",
  "maxRecords": 1000,
  "limit": 100
}' |
apify call datamule/opendatasoft-explore-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datamule/opendatasoft-explore-extractor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/DseLYynXkTOZ58w4m/builds/cnY2fqoZnJU7qXGM4/openapi.json