# API (データ)

## APIとは？

Application Programming Interface（アプリケーション・プログラミング・インターフェース）の略で、異なるソフトウェアプログラムがデータを交換し、相互作用できるようにする一連のルールまたはプロトコルです。

Listlyで**抽出したデータを自分のDB（データベース）に蓄積したり、Googleスプレッドシートに連携したい場合**にご利用ください。

{% hint style="info" %}
**超簡単チュートリアル**

➡️ 目的のデータ抽出結果を選択 ➡️ APIボタンをクリック ➡️（初回利用時）トークン生成 ➡️ APIトークンとAPIアドレスを取得
{% endhint %}

***

## APIアドレスの確認方法

LISTLY APIは、抽出されたデータを目的の場所に転送するための一種のデータ接続パイプライン（pipeline）として考えることができます。下の画像のように、すべてのデータ結果ページにAPIボタンがあり、APIボタンを押すと、その結果を指すAPIアドレスが表示されます。そのアドレスにアクセスすると、Excelで受け取ったデータが同じように表示されます。**この機能を活用してGoogleスプレッドシートに連携したり、追加コードを作成して自分のDBにデータを入れることができます。**

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

APIボタンを初めて使用する方は、下の画像のようにAPIトークン生成画面が表示されます。ワンクリックでトークンを生成し、結果ページに戻ってAPIボタンを再度押してください。

すでに設定済みの場合は、アカウント設定でAPIトークンを確認できます。

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

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

***

## APIアドレスの種類

APIアドレスは大きく2種類あります。

* 最新API：抽出成功した最新データのみを表示します。
* ログAPI：これまで抽出したすべてのデータを表示します。

シングル（Single）、グループ（Group）抽出結果ページで最新、ログAPIすべてを利用できます。

{% stepper %}
{% step %}

### シングル最新データ（Single Latest）

* シングル抽出最新データは結果で最新を選択後、APIで確認できます。
  {% endstep %}

{% step %}

### シングルログデータ（Single Logs）

* シングル抽出ログデータは結果でログを選択後、APIで確認できます。
  {% endstep %}

{% step %}

### グループ最新データ（Group Latest）

* **グループ抽出の最新データ**はグループAPIで確認できます。

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

{% step %}

### グループログデータ（Group Logs）

* グループ抽出**ログデータ**はログリスト → 目的のログデータを選択 → グループAPIで確認できます。

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

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

<details>

<summary><strong>最新APIレスポンスメッセージが {"message": " <code>Warning! Do not use this API endpoint</code>..." } と表示されます。</strong></summary>

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

このメッセージは、抽出するウェブページのデザインが変更されたときに表示されます。データ抽出は依然として自動で正常に行われていますが、ウェブページが変更されたことを知らせる一種の警告メッセージです。スケジューラー機能を使って自動収集している場合に発生する確率が高くなります。

原則として、Listly拡張機能から新たに抽出することをお勧めします。ウェブページのデザインが変わったため、新しい基準点を作ることが長期的に良いです。データを新たに抽出して新しい開始点を作り、スケジューラー設定を再度適用すると、その時から再び安定して最新APIを使用できます。

警告を無視して既存のデータをそのまま使用したい場合は、上記メッセージの「api\_endpoint」領域に表示されたアドレスを使用してください。この時、抽出された最新データが表示されますが、「api\_endpoint」に表示されたアドレスは既存のAPIアドレス + 警告メッセージを無視するオプション（\&ignore\_warning=y）が追加された値です。

</details>

### API Endpointの紹介

すべてのAPIアドレスは図のようにデータ抽出結果ページで確認できます。

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

| 種類         | URI                                                                                                                    | リクエスト方式 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------- | ------- |
| Single（最新） | [www.listly.io/api/single?key=](http://www.listly.io/api/single?key=)<mark style="color:red;">singlekey</mark>         | GET     |
|            | 最新データを表示します。スケジューラーで自動抽出される最新データを受け取る時に使用します。                                                                          |         |
| Single（ログ） | [www.listly.io/api/single/data?key=](http://www.listly.io/api/single/data?key=)<mark style="color:red;">datakey</mark> | GET     |
|            | すべてのログデータを表示します。これまで蓄積されたすべてのデータを一度に呼び出して検証する時に使用します。                                                                  |         |
| Group（最新）  | [www.listly.io/api/group?key=](http://www.listly.io/api/group?key=)<mark style="color:red;">groupkey</mark>            | GET     |
|            | 最新グループデータを表示します。                                                                                                       |         |
| Group（ログ）  | [www.listly.io/api/group/data?key=](http://www.listly.io/api/group/data?key=)<mark style="color:red;">datakey</mark>   | GET     |
|            | 選択したデータが属するバッチ（batch）グループのすべてのデータを表示します。新しいグループデータが蓄積されるたびにバッチ（batch）は1ずつ増加します。                                        |         |

### 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アドレスをコピーした時に開いていたデータ結果を指します。そのデータで選択したタブを基準に、同じデータを最新またはログデータから取得します。

| 名前       |     データ型 | 値                    | デフォルト値   | 説明                                                          |
| -------- | -------: | -------------------- | -------- | ----------------------------------------------------------- |
| selected |      int | 1, 2, 3...           | 1        | 選択したタブの位置です。 1は1番目、2は2番目を意味します。                             |
| arrange  |   string | y, n                 | y        | データ自動整列オプションです。 yは自動整列します。 nは自動整列なしで、表示された順序で左から詰めて出力します。   |
| href     |   string | y, n                 | n        | ハイパーリンク含有オプションです。 yはハイパーリンクを含みます。 nは含みません。                  |
| stack    |   string | vertical, horizontal | vertical | データを積む方法です。 verticalは上から下への垂直積みです。 horizontalは左から右への水平積みです。 |
| file     |   string | csv, json            | json     | データを出力する形式です。                                               |
| from     | datetime | 2020-11-01T00:00     |          | 日時でデータ範囲を制限できます。 fromは開始時点です。 %Y-%m-%dT%H:%Mで表現されます。        |
| to       | datetime | 2020-11-11T23:59     |          | 日時でデータ範囲を制限できます。 toは終了時点です。 %Y-%m-%dT%H:%Mで表現されます。          |

{% hint style="success" %}
**TIP** 上記の説明が理解しにくい場合は、実際のAPIアドレスで直接オプション値を変更してみてください。どのように変わるかすぐに確認できます。
{% endhint %}

***

## コードサンプル

**Pythonコード形式**

{% code title="download\_csv.py" %}

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

{% endcode %}

**Pythonコード実例**

{% code title="example\_download.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/ja/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.