# API (Data)

## What is an API?

Short for Application Programming Interface, it's a set of rules or protocols that allow different software programs to exchange data and interact with each other.

Use this in Listly **when you want to store extracted data in your own database or integrate it with Google Sheets**.

{% hint style="success" %}
**TIP** How to integrate with Google Sheets

Reference: [Importing Collected Data in Google Sheets (API Integration)](https://help.listly.io/docs/ko/getting-started/result-page-features/broken-reference)
{% endhint %}

{% hint style="info" %}
**Quick start**

➡️ Select desired data extraction result ➡️ Click API button ➡️ (First time) Generate token ➡️ Get API token and API URL
{% endhint %}

***

## How to check API URL

The LISTLY API can be thought of as a data pipeline for delivering extracted data to wherever you want. As shown below, every data result page has an API button, and clicking it reveals the API URL pointing to that result. Accessing that URL shows the same data you'd get in Excel. **Using this feature, you can integrate with Google Sheets or write additional code to put data into your own DB.**

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

For first-time API button users, a token generation screen appears as shown below. Generate the token with one click, return to the results page, and click the API button again.

If you've already configured it, you can check your API token in account settings.

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

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

***

## API URL Types

There are 2 main API URL types:

* Latest API: Shows only the latest successfully extracted data.
* Log API: Shows all data extracted over time.

You can use both latest and log APIs on Single and Group extraction result pages. Use the stepper below to see how to check each.

{% stepper %}
{% step %}

### Single Latest Data

* Single extraction latest data: Select latest in results then check API
  {% endstep %}

{% step %}

### Single Log Data

* Single extraction log data: Select log in results then check API
  {% endstep %}

{% step %}

### Group Latest Data

* Group extraction latest data: Check in Group API

<figure><img src="https://3090065457-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgoHfMCeMlqJPW61OR5d1%2Fuploads%2FyLvvhey8UeaXd4MCP2YE%2Fapi-data.png?alt=media&#x26;token=0dc001ec-7213-455c-be73-0ee0bf70a37f" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Group Log Data

* Group extraction log data: Check in log list → select desired log data → check in Group API

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

<figure><img src="https://3090065457-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgoHfMCeMlqJPW61OR5d1%2Fuploads%2FyLvvhey8UeaXd4MCP2YE%2Fapi-data.png?alt=media&#x26;token=0dc001ec-7213-455c-be73-0ee0bf70a37f" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

<details>

<summary><strong>Latest API response message is {"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/goHfMCeMlqJPW61OR5d1/blobs/cJZ3BeEhk2Qghxnzxo89/Untitled%205.png" alt=""><figcaption></figcaption></figure>

This message appears when the web page design has changed. Data extraction still works fine, but it's a warning that the web page has changed. This is likely to occur when using the scheduler feature for automatic collection.

In principle, we recommend extracting fresh from the LISTLY extension. Since the web page design changed, creating a new reference point is better long-term. Extract new data to create a new starting point, reapply scheduler settings, and from then on you can use the latest API stably again.

If you want to ignore the warning and use existing data as is, use the address shown in the "api\_endpoint" area of the message above. At this time, the latest extracted data appears, and the address shown in "api\_endpoint" is the existing API address + an option to ignore warnings (\&ignore\_warning=y).

</details>

### Introducing API Endpoints

All API URLs can be checked on the data extraction result page as shown in the image.

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

<table><thead><tr><th width="140.62">Type</th><th width="521.94">URI</th><th>Method</th></tr></thead><tbody><tr><td>Single (Latest)</td><td>www.listly.io/api/single?key=&#x3C;<mark style="color:red;">singlekey</mark>></td><td>GET</td></tr><tr><td></td><td>Shows latest data. Used to receive latest data auto-extracted by scheduler.</td><td></td></tr><tr><td>Single (Log)</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>Shows all log data. Used to import and review all accumulated data at once.</td><td></td></tr><tr><td>Group (Latest)</td><td>www.listly.io/api/group?key=&#x3C;<mark style="color:red;">groupkey</mark>></td><td>GET</td></tr><tr><td></td><td>Shows latest group data.</td><td></td></tr><tr><td>Group (Log)</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>Shows all data in the batch group containing the selected data. Batch increases by 1 each time new group data accumulates.</td><td></td></tr></tbody></table>

### Introducing API Parameters

**Single (Latest) Data API**

{% 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 %}

**Single (Log) Data API**

{% 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> points to the data result that was open when the user copied the API URL. Based on the tab selected in that data, it fetches the same data from latest or log data.

<table><thead><tr><th width="104.98">Name</th><th width="100.77">Type</th><th width="155.33">Values</th><th width="91.77">Default</th><th>Description</th></tr></thead><tbody><tr><td>selected</td><td>int</td><td>1, 2, 3...</td><td>1</td><td>Position of selected tab.<br>1 means 1st, 2 means 2nd.</td></tr><tr><td>arrange</td><td>string</td><td>y, n</td><td>y</td><td>Data auto-sort option.<br>y auto-sorts.<br>n outputs in order of appearance from left without auto-sorting.</td></tr><tr><td>href</td><td>string</td><td>y, n</td><td>n</td><td>Hyperlink inclusion option.<br>y includes hyperlinks.<br>n doesn't include them.</td></tr><tr><td>stack</td><td>string</td><td>vertical, horizontal</td><td>vertical</td><td>How to stack data.<br>vertical stacks top to bottom vertically.<br>horizontal stacks left to right horizontally.</td></tr><tr><td>file</td><td>string</td><td>csv, json</td><td>json</td><td>Data output format.</td></tr><tr><td>from</td><td>datetime</td><td>2020-11-01T00:00</td><td></td><td>Can limit data range by datetime.<br>from is the starting point.<br>Expressed as <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>Can limit data range by datetime.<br>to is the ending point.<br>Expressed as <mark style="color:red;background-color:$info;">%Y-%m-%dT%H:%M</mark>.</td></tr></tbody></table>

{% hint style="success" %}
**TIP** If the explanation above isn't clear, try changing option values directly in the actual API URL. You can immediately see how it changes.
{% endhint %}

***

## Code Samples

**Python Code Template**

```python
import requests
import csv

API_URL = "API URL"    # Enter 'API URL' of collected data
API_TOKEN = "API Token"     # Enter 'API Token' issued to your account
headers = { "Authorization": API_TOKEN }

# Load collected data
response = requests.get(url=API_URL, headers=headers)
content = response.content

# Save as CSV file
"""
If the file format loaded by API URL is JSON not CSV,
you need to use different code for that
"""
with open('./result.csv', 'wb') as f:
    f.write(content)
```

**Python Code Actual Example**

```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)
```


---

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