# API (추출데이터)

## API란?

애플리케이션 프로그래밍 인터페이스(Application Programming Interface)의 약자로 서로 다른 소프트웨어 프로그램이 서로 데이터를 교환하고 상호작용할 수 있도록 하는 일련의 규칙 또는 프로토콜입니다.

리스틀리에서 **추출한 데이터를 자신의 DB(데이터베이스)에 쌓아두거나 구글 스프레드 시트에 연동하고 싶을 때** 사용해보세요.

{% hint style="success" %}
**TIP** 구글 스프레트 시트에 연동하기

참고: [구글 시트에서 수집된 데이터 불러오기 (API 연동)](broken://pages/pSs0PNw84f7oIwHLmllt)
{% endhint %}

{% hint style="info" %}
**초간단 따라하기**

➡️ 원하는 데이터 추출 결과 선택 ➡️ API 버튼 클릭 ➡️ (처음 이용 시) 토큰 생성 ➡️ API 토큰과 API 주소 획득
{% endhint %}

***

## API 주소 확인하는 방법 

LISTLY API는 추출된 데이터를 원하는 곳으로 전달하기 위한 일종의 데이터 연결통로(pipeline)로 생각해볼 수 있습니다. 아래 이미지처럼 모든 데이터 결과 페이지에 API 버튼이 존재하며, API 버튼을 누르면 해당 결과를 가리키는 API 주소가 나타납니다. 해당 주소에 접속 시, 엑셀로 받아본 데이터가 동일하게 나타납니다. **이 기능을 활용해 구글 스프레드 시트에 연동하거나 추가 코드를 작성하여 자신의 DB 에 데이터를 넣으실 수 있습니다.**

<figure><img src="/files/aGdV6esjL9r4oYPgRHcl" alt=""><figcaption></figcaption></figure>

API 버튼을 처음 사용하시는 분들은 아래 이미지처럼 API 토큰 생성 화면이 나타납니다. 원클릭으로 토큰을 생성하시고, 결과 페이지로 돌아와 API 버튼을 다시 눌러보세요.

이미 설정을 한 경우라면 계정 설정에서 API 토큰을 확인하실 수 있습니다.

<figure><img src="/files/sFYsoAtsq2bBC7NJFcPu" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/I9uFFMYoqFNYvj6KYtMe" alt=""><figcaption></figcaption></figure>

***

## API 주소 종류

API 주소는 크게 2가지가 있습니다.

* 최신 API: 추출 성공한 최신 데이터만 보여줍니다.
* 로그 API: 그동안 추출한 모든 데이터들을 보여줍니다.

싱글 (Single), 그룹 (Group) 추출 결과 페이지에서 최신, 로그 API 들을 모두 사용하실 수 있습니다.

1. 싱글 최신 데이터 (Single Latest)
2. 싱글 로그 데이터 (Single Logs)
3. 그룹 최신 데이터 (Group Latest)
4. 그룹 로그 데이터 (Group Logs)

### 싱글 최신 데이터 (Single Latest) & 싱글 로그 데이터 (Single Logs)

* 싱글 추출 최신 데이터는 결과에서 최신 선택 후 API 확인
* 싱슬 추출 로그 데이터는 결과에서 로그 선택 후 API 확인

### 그룹 최신 데이터 (Group Latest) & 그룹 로그 데이터 (Group Logs)

* **그룹 추출의 최신 데이터**는 그룹 API 에서 확인

<figure><img src="/files/WUnhfVMbGX0FOOmCaC49" alt=""><figcaption></figcaption></figure>

* 그룹 추출 **로그 데이터**는 로그 목록 → 원하는 로그 데이터 선택 → 그룹 API에서 확인하실 수 있습니다.&#x20;

<figure><img src="/files/PZspDi76XnYMZ5cXAmdk" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Eh7XUGy7NAZzJRwmj0Yf" alt=""><figcaption></figcaption></figure>

<details>

<summary><strong>최신 API 응답 메세지가 {"message": "</strong><mark style="color:red;"><code>Warning! Do not use this API endpoint</code></mark>..."<strong>} 로 나옵니다.</strong></summary>

<figure><img src="/files/hGnUtH3lqowYhsjTG3Zv" alt=""><figcaption></figcaption></figure>

이 메시지는 추출하는 웹 페이지의 디자인이 바뀌었을 때 나타납니다. 데이터 추출은 여전히 자동으로 잘 되고 있지만, 웹 페이지가 변경되었음을 알리는 일종의 경고 메시지입니다. 스케줄러 기능을 이용해 자동 수집하고 있는 경우에 발생할 확률이 높습니다.

우선, 원칙적으로는 LISTLY 확장 프로그램에서 새로 추출하는 것을 추천합니다. 웹 페이지 디자인이 바뀌었기 때문에 새로운 기준점을 만드는 것이 장기적으로 좋습니다. 데이터를 새로 추출하여 새로운 시작점을 만들고 스케줄러 설정을 다시 붙이시면, 그 때부터 다시 안정적으로 최신 API 를 사용하실 수 있습니다.

만약 경고를 무시하고 기존 데이터를 그대로 사용하고 싶다면, 위 메시지에서 "api\_endpoint" 영역에 나타난 주소를 사용하시면 됩니다. 이 때 추출된 최신 데이터가 나타나는데, "api\_endpoint" 에 나타난 주소는 기존 API 주소 + 경고 메세지를 무시하는 옵션 (\&ignore\_warning=y) 이 더해진 값입니다.

</details>

### API Endpoint 소개

모든 API 주소는 그림과 같이 데이터 추출 결과 페이지에서 확인하실 수 있습니다.

<figure><img src="/files/V6KpsJFVvDfHehMHSY38" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="140.62109375">종류</th><th width="521.94140625">URI</th><th>요청방식</th></tr></thead><tbody><tr><td>Single (최신)</td><td>www.listly.io/api/single?key=&#x3C;<mark style="color:red;">singlekey</mark>></td><td>GET</td></tr><tr><td></td><td>최신 데이터를 보여줍니다. 스케쥴러로 자동 추출되는 최신 데이터를 받을 때 사용합니다.</td><td></td></tr><tr><td>Single (로그)</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>모든 로그 데이터를 보여줍니다. 그동안 쌓인 모든 데이터를 한 번에 불러와 검수할 때 사용합니다.</td><td></td></tr><tr><td>Group (최신)</td><td>www.listly.io/api/group?key=&#x3C;<mark style="color:red;">groupkey</mark>></td><td>GET</td></tr><tr><td></td><td>최신 그룹 데이터를 보여줍니다.</td><td></td></tr><tr><td>Group (로그)</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>선택한 데이터가 속한 배치(batch) 그룹의 모든 데이터를 보여줍니다. 새로운 그룹 데이터가 쌓일 때마다 배치(batch) 는 1씩 증가합니다.</td><td></td></tr></tbody></table>

### API Parameter **소개**

**Single (최신) 데이터 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 (로그) 데이터 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> 는 사용자가 API 주소를 복사할 때 열려 있었던 데이터 결과를 가리킵니다. 그 데이터에서 선택한 탭을 기준으로 하여, 동일한 데이터들을 최신 또는 로그 데이터에서 가져옵니다.

<table><thead><tr><th width="104.9765625">이름</th><th width="100.765625">자료형</th><th width="155.328125">값 </th><th width="91.76953125">기본값 </th><th>설명</th></tr></thead><tbody><tr><td>selected</td><td>int</td><td>1, 2, 3...</td><td>1</td><td>선택한 탭의 위치입니다.<br>1은 1번째, 2는 2번째를 뜻합니다.</td></tr><tr><td>arrange</td><td>string</td><td>y, n</td><td>y</td><td>데이터 자동정렬 옵션입니다.<br>y 는 자동 정렬합니다.<br>n 은 자동 정렬 없이 나타난 순서대로 왼쪽부터 차곡차곡 출력합니다.</td></tr><tr><td>href</td><td>string</td><td>y, n</td><td>n</td><td>하이퍼링크 포함 옵션입니다.<br>y 는 하이퍼링크를 포함합니다.<br>n은 포함하지 않습니다.</td></tr><tr><td>stack</td><td>string</td><td>vertical, horizontal</td><td>vertical</td><td>데이터를 쌓는 방법입니다.<br>vertical 은 위에서 아래로 수직쌓기를 합니다.<br>horizontal 은 왼쪽에서 오른쪽으로 수평쌓기를 합니다.</td></tr><tr><td>file</td><td>string</td><td>csv, json</td><td>json</td><td>데이터를 출력하는 형식입니다.</td></tr><tr><td>from</td><td>datetime</td><td>2020-11-01T00:00</td><td></td><td>날짜시간으로 데이터 범위를 제한할 수 있습니다.<br>from 은 시작하는 시점입니다.<br><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>날짜시간으로 데이터 범위를 제한할 수 있습니다.<br>to 는 끝나는 시점입니다.<br><mark style="color:red;background-color:$info;">%Y-%m-%dT%H:%M</mark>으로 표현됩니다.</td></tr></tbody></table>

{% hint style="success" %}
**TIP** 위의 설명이 잘 이해되지 않는다면, 실제 API 주소에서 직접 옵션값을 바꿔보세요. 어떻게 바뀌는지 바로 확인하실 수 있습니다.
{% endhint %}

***

## 코드 샘플

**Python 코드양식**

```python
import requests
import csv

API_URL = "API 주소"    # 수집된 데이터의 'API 주소' 를 입력하세요
API_TOKEN = "API 토큰"     # 나의 계정에 발급된 'API 토큰' 을 입력하세요
headers = {	"Authorization": API_TOKEN }

# 수집된 데이터를 불러오기
response = requests.get(url=API_URL, headers=headers)
content = response.content

# CSV 파일로 저장하기
"""
API 주소로 불러오는 파일의 양식이 CSV 가 아닌 JSON 일 경우
그에 맞는 다른 코드를 사용하셔야 합니다
"""
with open('./result.csv', 'wb') as f:
    f.write(content)
```

**Python 코드 실제 예시**

```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/docs/ko/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.