# API (datos)

## ¿Qué es una API?

Es la abreviatura de Interfaz de Programación de Aplicaciones (Application Programming Interface), un conjunto de reglas o protocolos que permiten a diferentes programas de software intercambiar datos e interactuar entre sí.

Usa esto cuando quieras **almacenar los datos extraídos con Listly en tu propia base de datos o conectarlos a Google Sheets**.

{% hint style="success" %}
**CONSEJO** Cómo conectar con Google Sheets

Referencia: [Importar datos recopilados en Google Sheets (Integración API)](https://help.listly.io/docs/ko/getting-started/result-page-features/broken-reference)
{% endhint %}

{% hint style="info" %}
**Guía rápida y sencilla**

➡️ Selecciona el resultado de extracción deseado ➡️ Haz clic en el botón API ➡️ (Si es la primera vez) Genera un token ➡️ Obtén el token API y la dirección API
{% endhint %}

***

## Cómo verificar la dirección API

La API de LISTLY puede considerarse como un conducto de datos (pipeline) para transferir datos extraídos a donde los necesites. Como se muestra en la imagen a continuación, cada página de resultados de datos tiene un botón API, y al hacer clic en él, aparece la dirección API correspondiente a ese resultado. Al acceder a esa dirección, verás los mismos datos que recibirías en Excel. **Puedes usar esta función para conectarla a Google Sheets o escribir código adicional para insertar los datos en tu propia base de datos.**

<figure><img src="https://content.gitbook.com/content/IB9ndOCr7FFgFMzgmMpx/blobs/WNevdYSiODLAPqj9dmMB/_2021_03_10_21_04_24_870.png" alt=""><figcaption></figcaption></figure>

Para quienes usan el botón API por primera vez, aparecerá una pantalla de generación de token API como se muestra en la imagen a continuación. Genera el token con un clic y regresa a la página de resultados para hacer clic nuevamente en el botón API.

Si ya has configurado esto antes, puedes verificar tu token API en la configuración de la cuenta.

<figure><img src="https://content.gitbook.com/content/IB9ndOCr7FFgFMzgmMpx/blobs/VzzeQbO7q9KIOhpYQzhs/Untitled.png" alt=""><figcaption></figcaption></figure>

<figure><img src="https://content.gitbook.com/content/IB9ndOCr7FFgFMzgmMpx/blobs/u6oIZkDffrOKPSXCBQnK/Untitled%201.png" alt=""><figcaption></figcaption></figure>

***

## Tipos de direcciones API

Hay principalmente 2 tipos de direcciones API:

* API más reciente: Muestra solo los datos extraídos con éxito más recientes.
* API de registro: Muestra todos los datos extraídos hasta ahora.

Puedes usar tanto las APIs más recientes como las de registro en las páginas de resultados de extracción Single (Individual) y Group (Grupal).

{% stepper %}
{% step %}

### Single Latest (Datos más recientes de Single)

Datos más recientes de extracción Single se verifican seleccionando "más recientes" en los resultados y confirmando la API.
{% endstep %}

{% step %}

### Single Logs (Datos de registro de Single)

Los datos de registro de extracción Single se verifican seleccionando "registro" en los resultados y confirmando la API.
{% endstep %}

{% step %}

### Group Latest (Datos más recientes de Group)

Los **datos más recientes de extracción grupal** se verifican en la API del grupo.

<figure><img src="https://content.gitbook.com/content/IB9ndOCr7FFgFMzgmMpx/blobs/xx8TEcnGQWePU3xFgrEX/Untitled%202.png" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Group Logs (Datos de registro de Group)

Los **datos de registro** de extracción grupal se pueden verificar en: Lista de registros → Seleccionar el registro de datos deseado → API del grupo.

<figure><img src="https://content.gitbook.com/content/IB9ndOCr7FFgFMzgmMpx/blobs/8PTJfvpgpE6PO2jTNVEi/Untitled%203.png" alt=""><figcaption></figcaption></figure>

<figure><img src="https://content.gitbook.com/content/IB9ndOCr7FFgFMzgmMpx/blobs/KK2pBXk44SrgkQDB1ZNT/Untitled%204.png" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

<details>

<summary><strong>El mensaje de respuesta de la API más reciente es {"message": "</strong><mark style="color:red;"><code>Warning! Do not use this API endpoint</code></mark>..."<strong>}</strong></summary>

<figure><img src="https://content.gitbook.com/content/IB9ndOCr7FFgFMzgmMpx/blobs/WPJMXpwy0XFdgI9H2dOd/Untitled%205.png" alt=""><figcaption></figcaption></figure>

Este mensaje aparece cuando el diseño de la página web que estás extrayendo ha cambiado. La extracción de datos sigue funcionando automáticamente bien, pero es un mensaje de advertencia que te informa que la página web ha cambiado. Es más probable que ocurra cuando usas la función de programador para recopil ar automáticamente.

En principio, recomendamos extraer de nuevo desde la extensión de LISTLY. Como el diseño de la página web ha cambiado, es mejor crear un nuevo punto de referencia a largo plazo. Si extraes los datos de nuevo para crear un nuevo punto de partida y vuelves a configurar el programador, podrás usar la API más reciente de forma estable desde ese momento.

Si deseas ignorar la advertencia y seguir usando los datos existentes, puedes usar la dirección que aparece en el área "api\_endpoint" en el mensaje anterior. En este caso, aparecerán los datos más recientes extraídos, y la dirección que aparece en "api\_endpoint" es la dirección API original + una opción que ignora el mensaje de advertencia (\&ignore\_warning=y).

</details>

### Introducción a los API Endpoints

Todas las direcciones API se pueden verificar en la página de resultados de extracción de datos como se muestra en la imagen.

<figure><img src="https://content.gitbook.com/content/IB9ndOCr7FFgFMzgmMpx/blobs/5wFyxUbCdsZ6T2L4R4AE/api%203.png" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="140.62109375">Tipo</th><th width="521.94140625">URI</th><th>Método de solicitud</th></tr></thead><tbody><tr><td>Single (más reciente)</td><td>www.listly.io/api/single?key=&#x3C;<mark style="color:red;">singlekey</mark>></td><td>GET</td></tr><tr><td></td><td>Muestra los datos más recientes. Se usa para recibir los datos más recientes que se extraen automáticamente mediante el programador.</td><td></td></tr><tr><td>Single (registro)</td><td>www.listly.io/api/single/data?key=&#x3C;<mark style="color:red;">datakey</mark>></td><td>GET</td></tr><tr><td></td><td>Muestra todos los datos de registro. Se usa para importar todos los datos acumulados de una vez y revisarlos.</td><td></td></tr><tr><td>Group (más reciente)</td><td>www.listly.io/api/group?key=&#x3C;<mark style="color:red;">groupkey</mark>></td><td>GET</td></tr><tr><td></td><td>Muestra los datos de grupo más recientes.</td><td></td></tr><tr><td>Group (registro)</td><td>www.listly.io/api/group/data?key=&#x3C;<mark style="color:red;">datakey</mark>></td><td>GET</td></tr><tr><td></td><td>Muestra todos los datos del lote (batch) del grupo al que pertenecen los datos seleccionados. El lote (batch) aumenta en 1 cada vez que se acumulan nuevos datos de grupo.</td><td></td></tr></tbody></table>

### Introducción a los parámetros API

**API de datos Single (más recientes)**

{% hint style="success" %}
[www.listly.io/api/single?key=](http://www.listly.io/api/single?key=)<mark style="color:red;">\<singlekey></mark>&<mark style="color:red;">**selected**</mark>=1&<mark style="color:red;">**arrange**</mark>=y&<mark style="color:red;">**href**</mark>=n&<mark style="color:red;">**file**</mark>=csv
{% endhint %}

**API de datos Single (registro)**

{% hint style="success" %}
[www.listly.io/api/single?key=](http://www.listly.io/api/single?key=)<mark style="color:red;">\<datakey></mark>&<mark style="color:red;">**selected**</mark>=1&<mark style="color:red;">**arrange**</mark>=y&<mark style="color:red;">**href**</mark>=n&<mark style="color:red;">**stack**</mark>=vertical&<mark style="color:red;">**file**</mark>=csv
{% endhint %}

<mark style="color:red;">\<datakey></mark> se refiere al resultado de datos que estaba abierto cuando el usuario copió la dirección API. Basándose en la pestaña seleccionada en esos datos, extrae datos idénticos de los datos más recientes o de registro.

<table><thead><tr><th width="104.9765625">Nombre</th><th width="100.765625">Tipo de dato</th><th width="155.328125">Valor</th><th width="91.76953125">Valor predeterminado</th><th>Descripción</th></tr></thead><tbody><tr><td>selected</td><td>int</td><td>1, 2, 3...</td><td>1</td><td>Es la posición de la pestaña seleccionada.<br>1 significa primero, 2 significa segundo.</td></tr><tr><td>arrange</td><td>string</td><td>y, n</td><td>y</td><td>Opción de ordenamiento automático de datos.<br>y ordena automáticamente.<br>n imprime en el orden de aparición sin ordenamiento automático, de izquierda a derecha.</td></tr><tr><td>href</td><td>string</td><td>y, n</td><td>n</td><td>Opción de inclusión de hipervínculos.<br>y incluye hipervínculos.<br>n no los incluye.</td></tr><tr><td>stack</td><td>string</td><td>vertical, horizontal</td><td>vertical</td><td>Método de apilamiento de datos.<br>vertical apila verticalmente de arriba hacia abajo.<br>horizontal apila horizontalmente de izquierda a derecha.</td></tr><tr><td>file</td><td>string</td><td>csv, json</td><td>json</td><td>Formato de salida de datos.</td></tr><tr><td>from</td><td>datetime</td><td>2020-11-01T00:00</td><td></td><td>Puedes limitar el rango de datos por fecha y hora.<br>from es el punto de inicio.<br>Se expresa como <mark style="color:red;background-color:$info;">%Y-%m-%dT%H:%M</mark>.</td></tr><tr><td>to</td><td>datetime</td><td>2020-11-11T23:59</td><td></td><td>Puedes limitar el rango de datos por fecha y hora.<br>to es el punto final.<br>Se expresa como <mark style="color:red;background-color:$info;">%Y-%m-%dT%H:%M</mark>.</td></tr></tbody></table>

{% hint style="success" %}
**CONSEJO** Si las explicaciones anteriores no te quedan claras, prueba cambiando los valores de las opciones directamente en la dirección API real. Podrás ver cómo cambia inmediatamente.
{% endhint %}

***

## Ejemplos de código

**Formato de código Python**

{% code title="import\_result.py" %}

```python
import requests
import csv

API_URL = "Dirección API"    # Ingresa la 'Dirección API' de los datos recopilados
API_TOKEN = "Token API"     # Ingresa el 'Token API' emitido para tu cuenta
headers = {	"Authorization": API_TOKEN }

# Importar los datos recopilados
response = requests.get(url=API_URL, headers=headers)
content = response.content

# Guardar como archivo CSV
"""
Si el formato del archivo importado por la dirección API no es CSV sino JSON
debes usar otro código apropiado para ello
"""
with open('./result.csv', 'wb') as f:
    f.write(content)
```

{% endcode %}

**Ejemplo real de código Python**

{% code title="example\_real.py" %}

```python
import requests
import csv

API_URL = "https://www.listly.io/api/single?key=CmKQ625S&selected=1&arrange=y&href=n&file=csv"
API_TOKEN = "BC1Sx370Yows25RxaBMuRxTuMKw3Aq0Ks"
headers = {	"Authorization": API_TOKEN }

response = requests.get(url=API_URL, headers=headers)
content = response.content

with open('./result.csv', 'wb') as f:
		f.write(content)
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.listly.io/docs/es/getting-started/result-page-features/api-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.