# EU Hotel & Tourism Occupancy Benchmark — Monthly, Per Record (`nexgensignal/eu-hotel-occupancy-benchmark-records`) Actor

Eurostat monthly tourism-accommodation statistics (tour\_occ\_nim) as clean, flat, per-record occupancy benchmarks — nights spent by accommodation type, guest residence (domestic/foreign) and country. Licence-clean, verbatim values, $0.05 per record.

- **URL**: https://apify.com/nexgensignal/eu-hotel-occupancy-benchmark-records.md
- **Developed by:** [NexGen Signal](https://apify.com/nexgensignal) (community)
- **Categories:** Business, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $33.50 / 1,000 occupancy 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/actors/running/actors-in-store.md#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

## EU Hotel & Tourism Occupancy Benchmark — Monthly, Per Record

Turn Eurostat's monthly tourism-accommodation cube into clean, per-record occupancy benchmarks — one row per published observation of nights spent, broken down by accommodation type, guest residence (domestic vs foreign) and country, ready to benchmark tourism demand across Europe month by month.

Each row of the source multidimensional cube becomes **one clean, flat record**: every dimension is
expanded into an explicit code **and** its human-readable label, the observation value is reproduced
exactly as Eurostat published it, and each record is stamped with source, dataset code, licence,
attribution, a UTC retrieval timestamp and an interpretation caveat. You get analysis-ready rows
instead of a nested JSON-stat blob you have to unpack yourself.

### What one record represents

The source dataset is Eurostat **`tour_occ_nim`** — monthly nights spent at tourist accommodation establishments. Eurostat publishes it as a
JSON-stat hypercube: a dense grid indexed by several dimensions (frequency, country of residence of the guest, unit, accommodation type (NACE Rev.2), geography and time) with a sparse
map of observed values. This Actor unpacks that cube so that **every present observation cell becomes
exactly one record**. Cells that Eurostat does not publish (genuinely missing observations) are absent
from the source `value` map and are therefore neither invented nor delivered — you receive only real,
published numbers. Published zeros are kept as real values, never dropped.

For each record you get the composite `record_id` (a stable, source-native key built from every
dimension code), the `dataset_code`, the `indicator` name, then — for each dimension — the dimension
**code** and its **label**, plus `time_period`, the numeric `value`, and Eurostat's `obs_status` flag
when one is present. The dimension columns include `c_resid` (residence of the guest — total, domestic, or foreign), `nace_r2` (accommodation type — hotels and similar, holiday and other short-stay, camping grounds), `unit` and `freq`.

### Coverage and volume

The live cube holds **193,830** licence-permitted, non-null monthly observations from 2015 onward across 44 territories, three residence breakdowns and several accommodation types — that is the record capacity of a full pull from 2015. This cube returns completely in a single request; a later start period or a single country yields a smaller, cheaper set.

Because the underlying cube is large, this Actor is built to pull it completely and safely. When the
full multi-territory request would exceed the dissemination API's single-response size limit, the
Actor automatically partitions the pull **by territory** and streams the partitions back, stopping as
soon as your **Maximum records** cap is met so you never wait for data you did not ask for. You can also pass a single **country code** (e.g. `DE`) to pull just that territory.

### Licence and attribution

This dataset is redistributed under the terms Eurostat publishes it with. The full notice travels on
every record in the `licence` field:

> Eurostat, CC BY 4.0. Reformatted from Eurostat JSON-stat; values unmodified. Third-party content and logos excluded. Commercial-barred geographies removed.

In addition, a structural **geography allow-list is applied at ingest**: only EU member states,
EU/euro-area aggregates, EFTA members and official EU acceding/candidate countries are delivered.
Territories that Eurostat marks as commercial-reuse-barred (for example non-European reporting
countries that sometimes appear in a cube) are **excluded at ingest and counted** in the run receipt,
so the delivered set is licence-clean by construction rather than by trust. The required attribution
string — `Source: Eurostat (dataset tour_occ_nim)` — is also present on every record.

### Interpretation caveat

Figures are nights spent at accommodation establishments by residence of guest and accommodation type — a demand volume, not an occupancy percentage, an average-daily-rate or a revenue figure. Read the `c_resid` and `nace_r2` dimensions to know whose nights and which accommodation type a row counts.

Eurostat values are reproduced verbatim: this Actor never rescales, re-bases, interpolates, seasonally
adjusts or otherwise transforms a number. Where a value is a rate, an index or a count is determined
by the dimension codes on the same record (read the `unit` / indicator dimensions), so always interpret
a value together with its dimension labels rather than in isolation.

### Person-data policy

City, airport and market identifiers describe **places and markets**, not people. The redundant city geocode/postal-address columns present in the raw source are intentionally excluded so no address-shaped field ever reaches the record. This is a statistics product about economies, industries, territories and markets.
If you need to enrich it with entity-level or contact data, do that in your own downstream systems
under your own lawful basis — it is deliberately out of scope here.

### Provenance, licensing and compliance

Every run begins with a live source-preflight: the Actor reads the exact host's `robots.txt` at
runtime and refuses to proceed if the crawl policy disallows the data path. The gate result — the URL
read, the HTTP status, the byte length and a SHA-256 of the policy document — is written to the run's
`RUN_RECEIPT` key-value record, so each run carries its own audit trail. The Actor identifies itself
with a transparent, non-impersonating User-Agent and never attempts to bypass a block, solve a
challenge, or fetch through a cache or mirror. When the door is genuinely unavailable the run fails
loudly and bills nothing rather than delivering a partial or stale set silently.

Records carry no natural-person or contact fields. The output schema is a fixed structural allow-list
of statistical, geographic and organisational columns; there are no name, email, phone, address, or
identifier-of-a-person fields anywhere in the record, and a per-record assertion enforces that
allow-list at write time. This is a records product about places, industries, markets and
organisations — never about people.

### Inputs

- **Earliest period** (`sinceTimePeriod`) — return observations from this period onward. Accepts a
  year (`2015`), a quarter (`2015-Q1`) or a month (`2015-01`) depending on the dataset's frequency.
  An earlier start yields more records. Leave **Country / territory** blank to pull all licence-permitted territories, or set a single Eurostat geo code (e.g. `DE`) to focus on one.
- **Maximum records** (`maxRecords`) — hard cap on records delivered and billed. Raise it to pull the
  full set; lower it to sample cheaply.

### Output

Records land in the Actor's default dataset and can be exported as JSON, CSV, Excel or fetched through
the Apify API. A tabular **overview view** surfaces the most useful columns — geography, period, the
key dimension labels and the value — for quick inspection, while the full record retains every code,
label and provenance field for downstream joins.

### Sibling Actors

This Actor is one cell of a broader per-record data fleet. It shares its engineering — the runtime
robots gate, the push-then-charge billing, the verbatim-value discipline and the person-data
allow-list — with the other Eurostat cells in the fleet (house prices, waste, migration, road freight,
business confidence and more) and with the fleet's other public-data records Actors. Each Actor targets
one dataset and one grain, so you pay only for the slice you need.

### Pricing

This Actor uses Apify's pay-per-event model. You are charged a flat **$0.05 per record** actually
delivered to the dataset — nothing else. There is no monthly rental, no per-run base fee, and no
charge for compute time. If a run delivers 40 records you pay $2.00; if it delivers 10,000 you pay
$500.00. The billing is wired *after* delivery: each record is pushed to the dataset first and only
then does the matching per-record event fire, so a mid-run failure can only ever under-charge you,
never over-charge. Set **Maximum records** to cap spend precisely — you will never be billed for more
than you asked for, and you will never be billed for records that were not delivered.

### Typical uses

Benchmark tourism demand by country and accommodation type; measure the domestic-vs-foreign guest mix; track seasonality and recovery month by month; feed a hospitality-market or destination-marketing model; or build a European tourism dashboard from clean monthly inputs.

### What this Actor does not do

It does not forecast, model, seasonally adjust, or editorialise the numbers; it does not merge multiple
Eurostat datasets into one record; and it does not deliver commercial-barred geographies. It gives you
faithful, licence-clean, analysis-ready observation records — one row per published cell — with a
provenance trail you can audit on every run.

# Actor input Schema

## `sinceTimePeriod` (type: `string`):

Return observations from this month onward. Use a year (2015) or a month (2015-01). Earlier start = more records. The multi-country cube is auto-partitioned by territory if it is too large for a single request.

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

Maximum records delivered and billed. You are billed only for records actually delivered. Raise it to pull the full set.

## `geo` (type: `string`):

Optional Eurostat geo code (e.g. DE). Leave blank to pull all licence-permitted territories (auto-partitioned if the full cube is too large for one request).

## Actor input object example

```json
{
  "sinceTimePeriod": "2015",
  "maxRecords": 500
}
```

# Actor output Schema

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

The delivered EU hotel & tourism occupancy record.

# 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 = {
    "sinceTimePeriod": "2015",
    "maxRecords": 500
};

// Run the Actor and wait for it to finish
const run = await client.actor("nexgensignal/eu-hotel-occupancy-benchmark-records").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 = {
    "sinceTimePeriod": "2015",
    "maxRecords": 500,
}

# Run the Actor and wait for it to finish
run = client.actor("nexgensignal/eu-hotel-occupancy-benchmark-records").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 '{
  "sinceTimePeriod": "2015",
  "maxRecords": 500
}' |
apify call nexgensignal/eu-hotel-occupancy-benchmark-records --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexgensignal/eu-hotel-occupancy-benchmark-records"
        }
    }
}

```

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/G2ddemN8lfr1tecTF/builds/PnD5B6eVOVINB1fCQ/openapi.json