API (データ)

APIとは？

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

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

超簡単チュートリアル

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

---

APIアドレスの確認方法

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

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

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

---

APIアドレスの種類

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

• 最新API：抽出成功した最新データのみを表示します。

• ログAPI：これまで抽出したすべてのデータを表示します。

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

1

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

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

2

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

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

3

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

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

4

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

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

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

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

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

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

API Endpointの紹介

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

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

API Parameterの紹介

Single（最新）データAPI

www.listly.io/api/single?key=<singlekey>&selected=1&arrange=y&href=n&file=csv

Single（ログ）データAPI

www.listly.io/api/single?key=<datakey>&selected=1&arrange=y&href=n&stack=vertical&file=csv

<datakey> は、ユーザーが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で表現されます。

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

---

コードサンプル

Pythonコード形式

download_csv.py

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コード実例

example_download.py

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)