# Italy Waste Management Registry – Albo Gestori Ambientali (`beyondforge/albo-gestori-ambientali`) Actor

Search Italy's Albo Gestori Ambientali by company name, Tax ID/VAT, region or province. Export public registration records, locations and category data.

- **URL**: https://apify.com/beyondforge/albo-gestori-ambientali.md
- **Developed by:** [Dario Mattioli](https://apify.com/beyondforge) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 registration records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Italy Waste Management Registry do?

**Search and export company registration records from Italy's Albo Nazionale Gestori Ambientali.** Look up a company by name, Italian tax code or VAT number, or browse a registry section and province. Results include identifiers, registration references, location and the categories returned by the public registry.

The source is the official [Elenchi iscritti](https://www.albonazionalegestoriambientali.it/Public/ElenchiIscritti). No registry account, password or proxy is needed for the supported searches. Run the Actor in Apify Console or through the Apify API, and use Apify's scheduling, exports and integrations to work with the results.

### Why use this Actor?

- Find a known company using its tax ID or VAT number.
- Build a list of public registration records for a selected region and province.
- Review category text alongside company and registration details.
- Export structured records for research, supplier screening or an internal reference database.

Results are source records for further review, not a certification of a company's current authorizations or suitability.

### How to search the Albo Gestori Ambientali

1. Open **Input** and choose **Search company** or **Browse by region / province**.
2. For company search, enter at least four characters of a company name, or a tax ID / VAT number. Choose a section or **All Italy**.
3. For browsing, choose a specific section and a province or **All provinces**.
4. Set **Maximum results** and start the Actor.
5. Open **Output** to review the records. Export the dataset as JSON, CSV, Excel or another format offered by Apify.

The ready-to-run example searches **HERA in Emilia Romagna**, across all provinces, with a limit of **10** records. If your Console retains an earlier input, use **Restore example input**.

### Input

| Field | Purpose | Default when omitted | Console example |
| --- | --- | --- | --- |
| `searchMode` | `company` for a name / tax ID search; `area` for browsing. | `"company"` | `"company"` |
| `query` | Name, Italian tax code or VAT number. Minimum 4 characters in company mode; ignored in area mode. | `"HERA"` | `"HERA"` |
| `region` | Section ID as a string, or `"ALL"` for company searches across Italy. | `"ALL"` | `"8"` |
| `province` | A code from the dropdown. Empty string means **All provinces**. | `""` | `""` |
| `maxResults` | Maximum records saved, from 1 to 10,000. Pagination is automatic. | `100` | `10` |

**Defaults and example input are different.** Apify applies schema defaults to omitted fields. The Console example uses the `prefill` values above.

#### Company name search

```json
{
  "searchMode": "company",
  "query": "HERA",
  "region": "8",
  "province": "",
  "maxResults": 10
}
```

Name search follows the registry's matching behavior and can include longer names containing the entered text. It is not an exact-name filter or relevance ranking.

#### Tax ID / VAT lookup across Italy

```json
{
  "searchMode": "company",
  "query": "04245520376",
  "region": "ALL",
  "province": "",
  "maxResults": 10
}
```

Use strings to preserve leading zeros. For an 11-digit numeric ID or 16-character alphanumeric tax code, the Actor checks for an exact returned `taxId` match. Once found, it keeps the exact matches collected so far and stops searching further sections. This lookup shortcut does not guarantee collection of every registration for that tax ID across Italy.

#### Browse a region and province

```json
{
  "searchMode": "area",
  "region": "8",
  "province": "BO",
  "maxResults": 150
}
```

Area mode requires a specific section. An incompatible province, such as Emilia Romagna (`8`) with Milano (`MI`), fails during input validation with an explanation and the accepted codes. Your choice is not silently changed.

#### Registry sections and provinces

| ID | Section | ID | Section | ID | Section |
| --- | --- | --- | --- | --- | --- |
| `13` | Abruzzo | `21` | Alto Adige | `17` | Basilicata |
| `18` | Calabria | `15` | Campania | `8` | Emilia Romagna |
| `6` | Friuli Venezia Giulia | `12` | Lazio | `7` | Liguria |
| `3` | Lombardia | `11` | Marche | `14` | Molise |
| `1` | Piemonte | `16` | Puglia | `20` | Sardegna |
| `19` | Sicilia | `9` | Toscana | `4` | Trentino |
| `10` | Umbria | `2` | Val d'Aosta | `5` | Veneto |

The registry has 21 sections because Trentino and Alto Adige are separate. Company searches with `ALL` visit sections in the order shown, stopping at the result limit, the spending limit or an exact tax ID match.

The province dropdown contains **111 codes from the official public lookup, verified on 17 September 2026**, plus All provinces. It is a complete static list and does not change with the selected region. Some source names are abbreviated and historical codes remain in the registry; these are preserved. With `company` + `ALL`, a selected province is sent unchanged to each section.

### Output

Each dataset item represents a company registration record. Deduplication uses company identifier, section and registration number, with a fallback based on tax ID and registration data. Several registrations can therefore share a tax ID.

This illustrative subset is based on HERA SPA from a validated lookup. Category values and source data may change.

```json
{
  "recordType": "company",
  "registryKey": "10043:BO:001653",
  "companyId": 10043,
  "companyName": "HERA SPA",
  "taxId": "04245520376",
  "registryRegion": "Emilia Romagna",
  "registryRegionId": "8",
  "registrationSection": "BO",
  "registrationNumber": "001653",
  "provinceCode": "BO",
  "city": "BOLOGNA",
  "postalCode": "40127",
  "address": "VIALE BERTI PICHAT, 2/4",
  "categories": ["1o A", "10B D", "2-bis", "R.Met A", "4 A", "5 B", "8 A"],
  "hasSuspendedCategory": false,
  "searchMode": "company",
  "searchQuery": "04245520376",
  "requestedProvince": null,
  "source": "Albo Nazionale Gestori Ambientali",
  "sourceUrl": "https://www.albonazionalegestoriambientali.it/Public/ElenchiIscritti"
}
```

### Data fields

| Fields | Meaning |
| --- | --- |
| `recordType`, `registryKey`, `companyId` | Record type, deduplication key and source company identifier. |
| `companyName`, `taxId` | Name and tax identifier returned by the registry. |
| `registryRegion`, `registryRegionId` | Section searched and its ID. |
| `registrationSection`, `registrationNumber`, `registrationNumberNumeric` | Registration references. The string number preserves leading zeros. |
| `provinceCode`, `city`, `postalCode`, `address` | Location fields from the public source. |
| `categories`, `categoriesRaw` | Category text split into an array, plus the cleaned original text. |
| `hasSuspendedCategory` | Whether category text contains `SOSPES`. This text-based flag is not a comprehensive legal status assessment. |
| `searchMode`, `searchQuery`, `requestedProvince` | Search context; unused query or province values are `null`. |
| `source`, `sourceUrl`, `retrievedAt` | Source reference and actual retrieval timestamp in UTC. |

Missing source values may be empty strings, empty arrays or `null`, depending on the field.

The default key-value store contains **`RUN_SUMMARY`** with `recordsSaved`, `requestedLimit`, `stopReason`, `chargeLimitReached`, `datasetItemsCharged`, API/HTTP request counts, visited sections and per-section pagination details. `stopReason` distinguishes `maxResults`, `endOfResults`, `chargeLimit` and the existing `exactTaxIdMatch` shortcut. The charged-item count is `null` under pay-per-usage pricing. Validation failures include `status: "failed"`, `stage: "inputValidation"` and an error message. A valid search with no matches succeeds with an empty dataset.

### How much does a run cost?

Pay Per Event pricing is **$0.005 per registration record saved** ($5 per 1,000 records), plus Apify's synthetic **$0.00005 Actor start event** at the default 256 MB memory. Platform usage is included in these event prices; Pay per event + usage is disabled. The primary event is **Registration record** (`apify-default-dataset-item`). A company may have several registration records, so this is not a price per unique company.

The minimum maximum cost per run is **$0.00505**, enough for one start and one registration record at 256 MB. To allow exactly 3 or 10 saved records, set the run budget to **$0.01505** or **$0.05005**, respectively. A valid search with no results costs only the start event. Review the current pricing and actual run cost in your Console. Apify scales the number of synthetic start events when allocated memory exceeds 1 GB; these examples assume the default 256 MB.

The Actor uses Apify's automatic start event and default-dataset-item event. Each successfully saved registration record counts as one dataset item. Duplicate registrations, API pages, retries and `RUN_SUMMARY` do not create additional dataset-item events. A search with no saved records creates no dataset-item events; the platform's start event still applies. The Actor checks the remaining budget before contacting the registry and before fetching another page, saves only affordable records, and stops successfully with `stopReason: "chargeLimit"` when it cannot afford another item. The chosen result limit and the available budget are both upper bounds.

Use a specific section when known and a small `maxResults` for initial checks. All Italy searches can require more requests, particularly when no match is found.

### Limits and search tips

- Only public company-name / tax-ID search and section/province browsing are supported. **Search by category, CER/EER waste code or activity type is not available.** The Actor does not access those login-restricted searches.
- Categories are returned fields, not search filters. Vehicle lists, waste-code details, documents, telephone numbers and email addresses are not extracted.
- Area browsing uses the standard registry scope with inclusion of own-account businesses disabled. The broader scope is not supported through the Console or API: `includeOwnAccount` must be omitted or explicitly `false`; any other value is rejected during input validation. Category `2-bis` may still appear among the categories of returned companies.
- `maxResults` is an upper limit, not a promise of that many matches. Pages contain up to 100 records; the Actor saves only as many unique records as needed.
- National text searches follow section/source order, not a balanced sample or national ranking. A low limit may be reached before later sections are visited.
- The province list reflects the registry snapshot above. Source changes may require a maintenance update.
- Records are normalized, deduplicated and saved progressively in batches of at most one page. For tax-ID lookups, provisional non-exact candidates are held on temporary disk until the existing exact-match selection is settled, then discarded or saved in batches. This preserves the lookup behavior without charging candidates that may later be discarded. The existing candidate limit also applies before this exact-match filtering.
- Temporary registry failures are retried. An unresolved source or dataset-write failure makes the run fail; records confirmed as saved before the failure remain in the dataset. Check `RUN_SUMMARY` for the confirmed saved count. `writeOutcomeUnknown: true` flags a dataset write whose outcome could not be confirmed.

### FAQ

#### Do I need credentials for the official registry?

No. The supported functions use public endpoints without registry authentication.

#### Can I browse every company in Italy in one area search?

No. Area mode requires one section. All Italy is available for company queries of at least four characters, including tax ID / VAT searches.

#### Why does HERA return names other than HERA SPA?

The registry can match a sequence inside a longer name. Use the complete tax ID for a targeted lookup.

#### Does an empty dataset mean the Actor failed?

No. A valid search with no matches succeeds. Check `RUN_SUMMARY` to distinguish zero results from failure.

#### Can I filter by category or CER code?

No. You can analyze category text after export, but the Actor does not perform the authenticated category, waste-code or activity-type searches.

#### Is this an official service?

No. This independent Actor **is not affiliated with or endorsed by the Albo Nazionale Gestori Ambientali**. Data belongs to its respective source. Check the official registry for authoritative, current information and use exported records responsibly under the rules applicable to your use case.

For support, provide the run URL, input and expected behavior to the developer through Apify. Do not include passwords or API tokens.

# Actor input Schema

## `searchMode` (type: `string`):

Choose whether to search for a company or browse registration records by area.

## `query` (type: `string`):

Used in Search company mode. Enter at least 4 characters of a company name, or an Italian Tax ID / VAT number.

## `region` (type: `string`):

Select a registry section. In Search company mode, All Italy visits sections in source order until the result limit, spending limit or an exact Tax ID match is reached. Browse by region requires a specific section.

## `province` (type: `string`):

Choose All provinces or a province from the official registry lookup (verified 17 September 2026). This complete list does not change with the selected region. In Browse mode, the province must belong to the selected registry section. In Search company mode with All Italy, the chosen province is passed to each section.

## `maxResults` (type: `integer`):

Maximum number of registration records to save to the dataset, subject to the run budget. A company can have multiple registration records. The Actor automatically handles pagination.

## Actor input object example

```json
{
  "searchMode": "company",
  "query": "HERA",
  "region": "8",
  "province": "",
  "maxResults": 10
}
```

# Actor output Schema

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

No description

## `runSummary` (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 = {
    "searchMode": "company",
    "query": "HERA",
    "region": "8",
    "province": "",
    "maxResults": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("beyondforge/albo-gestori-ambientali").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 = {
    "searchMode": "company",
    "query": "HERA",
    "region": "8",
    "province": "",
    "maxResults": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("beyondforge/albo-gestori-ambientali").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "searchMode": "company",
  "query": "HERA",
  "region": "8",
  "province": "",
  "maxResults": 10
}' |
apify call beyondforge/albo-gestori-ambientali --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,beyondforge/albo-gestori-ambientali"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/dulaBRchXhuENMm3d/builds/9iA08SLQdTraZ8d5U/openapi.json