1. 概要

Octoparse API を使用する前に、少なくとも 1 つの実行可能なタスクが設定されてください。なお、スタンダードプラン、またはプロフェッショナルプランのアカウントが必要です。(アカウントをお持ちでない方は、 こちらから登録してください。) Octoparse API に接続することで、抽出されたデータやタスク情報、さらにはタスクのコントロール (アドバンスド API) まで簡単に取得することができ、ご自身のアプリケーションとの連携による効率的なデータ抽出を実現できます。

1.1. ドキュメントのバージョン

現在のバージョン: V1.0

1.2. 連絡先

連絡先: Octoparse support team

Email: support@octoparse.jp

1.3. URL 標準

すべてのリクエストは以下のベース URL でエンコードされた URL であります。

https://dataapi.octoparse.com/

例として、「オフセットによるデータを取得する」のリクエストは、次のようになります:GET http://dataapi.octoparse.com/api/alldata/GetDataOfTaskByOffset?taskId={taskId}&offset={offset}&size={size}

注:このドキュメントの{xxxx}はプレースホルダを表しており、ユーザーはこれを実際の値に置き換える必要があります。例として、タスク ID が abc、オフセットが 1、サイズが 10 の場合、URL は https://dataapi.octoparse.com/api/alldata/GetDataOfTaskByOffset?taskId=abc&offset=1&size=10 となります。

1.4. OAuth2.0 アクセストークンを取得する

Octoparse API にアクセスする前に、OAuth2.0 に基づく Access Token を取得する必要があります。

1.4.1. 新アクセストークンを取得する

新しいアクセストークンを取得するには、ユーザー名とパスワードが必要です。

リクエスト

POST https://dataapi.octoparse.com/token

パラメーター

username={userName}&password={password}&grant_type=password

リクエストのContent-Type

application/x-www-form-urlencoded

レスポンス

Access Token

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
    "access_token": "ABCD1234",      //アクセストークン
    "token_type": "bearer",		     //トークンタイプ
    "expires_in": 86399,		     //アクセストークンの有効期限(秒)(有効期限内に同じトークンを繰り返し使用することをお勧めします) 
    "refresh_token": "refresh_token" //認可コード(アクセストークンを更新する際に使用します)
}

API メソッドを呼び出す際には、「Access_Token」が必要です。以下の形式で HTTP ヘッダに追加してください。

HeaderName: Authorization
Value: bearer {access_token}

注:「bearer」と「access_token」の間にはスペースがある。例として、Access Token が AA11BB22...CC33 の場合、ヘッダは「Authorization: bearer AA11BB22...CC33」とします。 Access Token には有効期限がありますので、有効期限内に同じトークンを繰り返し使用することをお勧めします。

1.4.2. アクセストークンを更新する

アクセストークンの有効期限が切れると、ユーザーは「refresh_token」でアクセストークンを更新することができます。「Refresh Token」は、ユーザー名とパスワードに通じて新トークンを取得の方がより安全です。

注: 各「refresh_token」は一度しか使用できません。現在のリクエストから返された新「Refresh Token」は、次のリクエストに使用されるべきです。

リクエスト

POST https://dataapi.octoparse.com/token

パラメーター

refresh_token={refresh_token}&grant_type=refresh_token

リクエストのContent-Type

application/x-www-form-urlencoded

レスポンス

Access Token

注: レスポンス HTTP ステータスコードは「200」でなければなりません。そうでない場合は、HTTP ステータスコードを参照して問題を解決してください。

2. 手順

Octoparse は API の使用を 20 リクエスト / 秒に制限されています。ステータスコード「429」を受信した場合は、アクセス頻度を下げてください。

注: Octoparse は、API アクセス頻度を制限するためにリーキーバケットアルゴリズムを使用します。リクエストの最大数は、任意の 5 秒間の時間間隔内で、100 になります。

異常なHTTPステータスコード

レスポンス HTTP ステータスコードは「200」でなければなりません。そうでない場合は、HTTP ステータスコードを参照して問題を解決してください。

2.1. タスクグループ情報を取得する

2.1.1.すべてのタスクグループの情報をリストアップする

リクエスト

GET api/TaskGroup

レスポンス

タスクグループ情報とリクエストステータスを含む JSON 形式のテキスト。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": [
    {
      "taskGroupId": 1,
      "taskGroupName": "Example Task Group 1"
    },
    {
      "taskGroupId": 2,
      "taskGroupName": "Example Task Group 2"
    }
  ],
  "error": "success",
  "error_Description": "Operation successes."
}

2.2. タスクを管理する

2.2.1.グループ内のタスク一覧を表示する

リクエスト

GET api/Task?taskGroupId={taskGroupId}
パラメーター
パラメーター 説明 備考
taskGroupId

タスクグループ ID

リクエスト URL にパラメーターを定義してください。

レスポンス

タスク ID(taskId)、タスク名(taskName)、ユーザー ID とリクエストステータスを含む JSON 形式のテキスト。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": [
    {
      "taskId": "337fd7d7-aded-4081-9104-2b551161ccc8",
      "taskName": "Example Task 1",
      "creationUserId": "5d1e4b3c-645c-44ab-ac0e-bfa9ad600ece"
    },
    {
      "taskId": "4adf489b-f883-43fa-b958-0cfde945ddb7",
      "taskName": "Example Task 2",
      "creationUserId": "5d1e4b3c-645c-44ab-ac0e-bfa9ad600ece"
    }
  ],
  "error": "success",
  "error_Description": "Operation successes."
}

2.2.2.データをクリアする

リクエスト

POST api/task/RemoveDataByTaskId?taskId={taskId}
パラメーター
パラメーター 説明 備考
taskId

タスク ID

リクエスト URL にパラメーターを定義してください。

レスポンス

データが正常にクリアされたかどうかを表示されます。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "error": "success",
  "error_Description": "Operation successes."
}

2.3. データを抽出する

2.3.1.データをエクスポートする

エクスポートされていないデータをエクスポートします。データは、エクスポート後に(status=exported ではなく)status=exporting とタグ付けされます。この方法では、同じデータセットをこの方法で複数回エクスポートすることができます。データが正常に取得されていることを確認した後、データのステータスを「exported」に更新したい場合は、2.3.2 の手順でステータスの更新を行ってください。

注:エクスポートが中断された場合(ネットワークの接続中断など)、この方法を使用して再度データをエクスポートしてください。

リクエスト

GET api/notexportdata/gettop?taskId={taskId}&size={size}
パラメーター
パラメーター 説明 備考
taskId

タスク ID

リクエスト URL にパラメーターを定義してください。

size

データ行数(1 ~ 1000行)

リクエスト URL にパラメーターを定義してください。

レスポンス

データとリクエスト状態

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": {
    "total": 100000,
    "currentTotal": 4,
    "dataList": [
      {
        "state": "Texas",
        "city": "Plano"
      },
      {
        "state": "Texas",
        "city": "Houston"
      },
      {
        "state": "Texas",
        "city": "Austin"
      },
      {
        "state": "Texas",
        "city": "Arlington"
      }
    ]
  },
  "error": "success",
  "error_Description": "Operation successes."
}

2.3.2.データの状態を更新する

これにより、データの状態が「exporting(抽出中)」から「exported(抽出完了)」に更新されます。

注:API「タスクデータのエクスポート」(api/notexportdata/gettop)からエクスポートされたデータが正常に取得されていることを確認した上で、この方法を使用してください。

リクエスト

POST api/notexportdata/update?taskId={taskId}
パラメーター
パラメーター 説明 備考
taskId

タスク Id

リクエスト URL にパラメーターを定義してください。

レスポンス

タスクの状態が正常に変更されたかどうかを表示されます。

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "error": "success",
  "error_Description": "Operation successes."
}

2.4. データを取得する

2.4.1.オフセットによるデータを取得する

このメソッドには、リクエストにはオフセット、サイズ、タスク ID などのパラメーターが必要です。 オフセットのデフォルト値は 0 (offset=0)、サイズは size∈[1,1000] とします。返されたオフセット(offset > 0)は、次のリクエストに使用されます。 例として、タスクは 1000 行のデータがある場合、パラメーター:offset = 0, size = 100 を使用すると、最初の 100 行のデータとオフセット x(x は必ずしも 100 とは限らない)が返されます。 2 回目のリクエストを行う場合、最初のリクエストから返されたオフセット、offset = X, size = 100 を使用して、 次の 100 行のデータ(101 行目から 200 行目まで)を取得し、次のオフセット offset=x1 も返されました。x1 を次の開始オフセットとして使用する、というようにしています。

注:この方法はデータを取得するためだけに使用されますが、データの状態には影響しません。(エクスポートされていないデータはエクスポートされていない状態のままになります)

リクエスト

GET api/alldata/GetDataOfTaskByOffset?taskId={taskId}&offset={offset}&size={size}
パラメーター
パラメーター 説明 備考
taskId

タスク ID

リクエスト URL にパラメーターを定義してください。

offset

オフセットが 0 以下の場合は、最初の行からデータが返されます。

リクエスト URL にパラメーターを定義してください。

size

取得データ量(1~1000の範囲)

リクエスト URL にパラメーターを定義してください。

レスポンス

データとリクエスト状態

レスポンスのContent-Type

application/json, text/json

レスポンスの例
{
  "data": {
    "offset": 4,
    "total": 100000,
    "restTotal": 99996,
    "dataList": [
      {
        "state": "Texas",
        "city": "Plano"
      },
      {
        "state": "Texas",
        "city": "Houston"
      },
      {
        "state": "Texas",
        "city": "Austin"
      },
      {
        "state": "Texas",
        "city": "Arlington"
      }
    ]
  },
  "error": "success",
  "error_Description": "Operation successes."
}

3. 参照

3.1. HTTP ステータスコード

エラーコードが返ってきた場合は、以下のステータスコード表を参照して問題を解決してください。

HTTP ステータスコード Inner ステータスコード 説明

200

ok

操作は成功しました。

400

invalid_grant

ユーザー名またはパスワードが間違っています。

400

unsupported_grant_type

POST形式が正しくありません。正しいフォーマットは、username={username}&password={password}&grant_type=passwordです。

401

unauthorized

アクセストークンの有効期限が切れているか、不正のため無効です。新アクセストークンを取得してください。

403

user_not_allowed

許可が拒否されました。データ API をご利用になる場合はスタンダードプランへ、アドバンスド API をご利用になる場合はプロフェッショナルプランへアップグレードしてください。

404

not_found

HTTP リクエストが認識されません。正しい URL でリクエストしてください。

405

method_not_allowed

HTTP メソッドはサポートされていません。インターフェースでサポートされている方法を使用してください。

429

quota_exceeded

リクエスト回数が制限値を超えています。アクセス頻度を 20 回/秒以下にしてください。

503

service_unavailable

サービスは一時的に利用できません。あとでもう一度お試しください。

3.2. サンプルコード

サンプルコード:

C#: ApiSamples/Code/CSharp/

Python: ApiSamples/Code/Python/

(他の言語も近日中にリリース予定です。)

3.3. 利用規約

利用規約