# Afluencia de Lugares Chile — Horarios populares (`scraperschile/afluencia-lugares-chile`) Actor

Consulta horarios populares semanales, actividad en vivo disponible y duración habitual de visita de lugares en Chile. Exporta señales relativas para planificar visitas y analizar ubicaciones; no son conteos de personas.

- **URL**: https://apify.com/scraperschile/afluencia-lugares-chile.md
- **Developed by:** [Scrapers Chile](https://apify.com/scraperschile) (community)
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.40 / 1,000 lugar con afluencias

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

## Afluencia de Lugares Chile — Horarios populares

Consulta la actividad relativa de lugares en Chile. Entrega el perfil semanal por hora, el nivel en vivo cuando está disponible y la duración habitual de la visita cuando la fuente la informa. Descarga los resultados en Excel, CSV o JSON desde Apify.

### Uso desde el formulario de Apify

1. Pega uno o más enlaces de fichas de Google Maps en **Enlaces de lugares de Google Maps**. También puedes utilizar Place IDs o búsquedas por categoría y ubicación.
2. Activa **Incluir afluencia en vivo** si necesitas ese dato cuando esté disponible.
3. Inicia la ejecución y revisa **Resultados**. Cada fila corresponde a un lugar con un perfil semanal validado.
4. Exporta los resultados para comparar horarios del mismo lugar o preparar una visita al entorno de un local comercial.

Para evaluar un posible local comercial, combina su arriendo y superficie con los horarios de negocios cercanos. Es una ayuda para preparar visitas: no mide el tránsito frente al inmueble ni demuestra ventas o rentabilidad.

### Qué significa la afluencia

Los valores de 0 a 100 son relativos al momento de mayor actividad del mismo lugar. No representan cantidades de personas y no deben utilizarse para comparar directamente dos locales distintos. Un valor ausente se entrega como `null`; el Actor nunca lo reemplaza por cero.

La fuente es la interfaz pública de Google Maps. Este proyecto es no oficial y no está afiliado, patrocinado ni aprobado por Google.

### Entradas

Puedes combinar:

- `placeUrls`: enlaces normales o cortos de lugares.
- `placeIds`: identificadores de Google Places.
- `searches`: búsquedas por categoría, ubicación y, opcionalmente, coordenadas y radio.
- `includeLive`: solicita el dato en vivo; está activo por defecto.
- `proxyConfiguration`: permite Apify Proxy o proxies propios.

Ejemplo de búsqueda:

```json
{
  "searches": [
    {
      "query": "supermercados",
      "location": "Providencia, Chile",
      "maxPlaces": 5
    }
  ],
  "includeLive": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

Cada búsqueda devuelve una selección no exhaustiva de hasta 50 lugares. La ejecución admite como máximo 100 solicitudes de navegador, tres pestañas simultáneas, dos intentos por lugar y una sola rotación de proxy. Los enlaces entregados directamente tienen prioridad cuando aparece el mismo Place ID en una búsqueda.

### Resultado

El dataset predeterminado contiene únicamente lugares con una estructura semanal validada de siete días. Cada día incluye 24 horas: `available: false` y `relativePopularity: null` indican que la fuente no entregó esa hora; un cero solo aparece cuando la fuente informó cero explícitamente. Un día completo puede quedar sin observaciones si Google lo indica; no se interpreta como actividad cero.

Campos principales:

- lugar, dirección, Place ID, coordenadas, zona horaria y enlace canónico;
- perfil de lunes a domingo, hora por hora;
- afluencia en vivo y texto original, cuando existe;
- duración habitual mínima y máxima, cuando se puede interpretar con seguridad;
- consulta, posición, extracción UTC y hora local.

### Estados y comportamiento seguro

El Actor distingue `ok`, `no_data`, `not_found`, `invalid_input`, `blocked`, `temporary_source_error` y `source_changed`.

`no_data` solo se usa cuando el lugar queda identificado y la interfaz muestra explícitamente que no existe información de horarios populares. Un campo estructurado vacío, por sí solo, se trata como un posible cambio de fuente y hace fallar la ejecución. Si Google muestra CAPTCHA, exige login, bloquea ambos intentos o cambia un formato que no puede validarse, la ejecución falla sin guardar resultados parciales.

Los diagnósticos se guardan por separado en `DIAGNOSTICS`. Incluyen códigos, tiempos y conteos, pero no almacenan páginas, respuestas internas, cookies, tokens ni parámetros de seguimiento. No se crean filas diagnósticas en el dataset.

### Precio configurado

El uso de plataforma está incluido. En los planes Free y Bronze, cada ejecución cuesta USD 0,005 por el inicio con 2 GB de memoria, más USD 0,003 por cada lugar válido guardado. En Silver son USD 0,0044 más USD 0,0027 por lugar; en Gold, Platinum y Diamond son USD 0,004 más USD 0,0024 por lugar.

El cobro por resultado utiliza el evento sintético del dataset de Apify: solo se cobra una fila después de que quedó guardada. `no_data`, `not_found`, bloqueos y diagnósticos no generan cobros por resultado. Si el usuario fija un límite de gasto que no admite todas las filas, el Actor entrega únicamente las que caben dentro de ese límite y marca la salida como `partial`.

### Extracción

El navegador reutilizable utiliza Scrapling 0.4.15 con idioma `es-CL` y zona `America/Santiago`. Primero intenta validar las respuestas estructuradas internas y `APP_INITIALIZATION_STATE`. Si eso no entrega una semana válida, utiliza como respaldo la región accesible de horarios populares y la relocalización adaptativa de Scrapling. El respaldo solo se acepta si confirma la identidad del lugar, los siete días y una estructura horaria válida.

Se bloquean imágenes, videos y fuentes para reducir tiempo y memoria, pero se conservan JavaScript, estilos y solicitudes necesarias para Maps. No se intenta eludir CAPTCHA, login ni controles persistentes.

### Límites de esta versión

- Google puede no publicar horarios populares, afluencia en vivo o duración para un lugar.
- La búsqueda por área no representa un censo completo.
- La actividad depende de una fuente externa y puede cambiar o dejar de estar disponible.
- Google puede entregar versiones distintas de la ficha según la conexión. El proxy es opcional; si esa ruta no permite validar los horarios, la ejecución falla sin convertir la ausencia incierta en cero.

Consulta las [condiciones de Google Maps](https://maps.google.com/help/terms_maps/) y las [condiciones de publicación de Apify](https://docs.apify.com/legal/store-publishing-terms-and-conditions). La disponibilidad de información depende de Google Maps y no implica una autorización general para cualquier uso posterior.

### Desarrollo local

```bash
python -m pip install -r requirements.txt
scrapling install
python -m unittest discover -s tests -p 'test_*.py' -v
python -m py_compile afluencia_scraper.py maps_client.py src/__main__.py
```

Para usar Google Chrome ya instalado localmente, define `SCRAPLING_BROWSER_EXECUTABLE` con la ruta del ejecutable. La imagen del Actor fija Python, Playwright, Patchright y la imagen base por digest.

Consulta [THIRD\_PARTY\_NOTICES.md](../THIRD_PARTY_NOTICES.md) para las dependencias y referencias técnicas utilizadas.

# Actor input Schema

## `placeUrls` (type: `array`):

Enlaces normales o cortos de lugares. Los enlaces cortos se validan en cada redirección y nunca se siguen hacia dominios externos.

## `placeIds` (type: `array`):

Identificadores públicos de lugares. Los duplicados se eliminan antes de guardar resultados.

## `searches` (type: `array`):

Ejemplo: supermercados en Providencia. Cada búsqueda entrega una selección no exhaustiva de hasta 50 lugares.

## `includeLive` (type: `boolean`):

Entrega actividad actual cuando Google la publica. Su ausencia nunca se reemplaza por cero.

## `proxyConfiguration` (type: `object`):

Puedes usar Apify Proxy o proxies propios. Como máximo se realizan dos intentos y una rotación por lugar.

## Actor input object example

```json
{
  "includeLive": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `status` (type: `string`):

ok, no\_results, partial o failed. partial solo indica que el límite de gasto del usuario permitió entregar una parte de los lugares válidos.

## `resultCount` (type: `string`):

Cantidad de lugares guardados en el dataset.

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

Lugares con perfil semanal validado.

## `diagnostics` (type: `string`):

Estados y códigos técnicos sin respuestas internas, cookies, tokens ni parámetros de seguimiento.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("scraperschile/afluencia-lugares-chile").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("scraperschile/afluencia-lugares-chile").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 '{}' |
apify call scraperschile/afluencia-lugares-chile --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scraperschile/afluencia-lugares-chile"
        }
    }
}
```

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/aLdtiPN01BFqbzf1V/builds/CACeBjgs4cg6eP0gb/openapi.json