商会ショップ検索 WebAPI v1 について


本ドキュメントは、商会ショップ検索が提供している WebAPI v1 について記述したものです。


## 提供する機能

- ショップ検索機能
  - 商会ショップ検索サイトで提供している検索機能を WebAPI で提供するものです。
- 検索対象候補の取得
  - 検索フォームのインクリメンタルサーチで提供している、指定したキーワードにマッチするアイテム名または商会名、ブースト対象のスキル名を返します。
- 価格推移情報の取得
  - 指定したアイテムの直近 100 件分の価格推移を取得します。アイテムは検索で取得できるアイテム ID で指定します。
- ワールド情報の取得
  - 現時点での各ワールドの総キャラクタ数、商会数、出展物の合計金額を取得します。
- 同盟港変動情報の取得
  - クローリングのタイミングで同盟港が変動していた場合の変動情報を取得します。
- 都市名→都市IDテーブル取得
  - ショップ検索 API で都市を指定する場合、システム内で採番された都市 ID を指定する必要があります。この API では都市名から都市 ID を引くためのテーブルを返します。
  - ここで返される ID は、@Web で内部的に採番されている ID と同一です。


## 呼び出し方法

- 各 WebAPI を呼び出す際は、それぞれの API エンドポイントに対して HTTPS に準拠して呼び出します。URI は RESTful 風になっていますが、原則としてデータの取得のみのため、すべて GET メソッドで行ってください。
- POST など他のメソッドでも動作しますが、動作を保証するものではありません。
- 引数・戻り値ともにマルチバイト文字列は UTF-8 でエンコードされます。引数にマルチバイト文字列を与える場合は必ず URL エンコードしてください。
- 戻り値は JSON で返されますが、エラー時には JSON で返される保証はありません。必ず HTTP ステータスコードで判定してください。

### ショップ検索機能

#### エンドポイント

```
https://search.meixiaojie.com/api/v1/search/[ワールド名]/[都市ID]/[クエリ]
```

#### 引数

##### URI

- ワールド名:
  - 以下文字列を与えます。
    - `all`: すべてのワールド
    - `astraios`: Astraios のみ
    - `eos`: Eos のみ
- 都市 ID:
  - @Web 内部の ID を指定します。都市IDテーブル取得 API から取得可能です。
  - 都市を指定しない場合は `0` を指定します。
  - 複数の都市を指定する場合は、「`,`」で区切ってください。
  - 商会名検索の場合は「`-`」を指定してください。
- クエリ
  - 検索対象の文字列。必ず URL エンコードしてください。

##### クエリストリング

- `target`: 検索対象を指定します。
  - `1`: アイテム名
  - `2`: 商会名
  - `3`: ブースト
- `conj`: 検索時の結合条件を指定します。
  - `0`: 半角スペースで区切ったキーワードのいずれかを含む
  - `1`: 半角スペースで区切ったキーワードすべてを含む
  - `2`: 完全一致
- `price_from`: 検索対象の価格下限を指定します。
- `price_to`: 検索対象の価格上限を指定します。
- `sex`: 装備品の性別を指定します。
  - `0`: 性別を指定しない
  - `1`: 男性専用
  - `2`: 女性専用
  - `3`: 性別制限がないもののみ
- `order`: 検索結果のソート方法を指定します。
  - `1`: 価格 + 原価
  - `2`: 原価
  - `3`: 貫通
  - `4`: 攻撃力
  - `5`: 防御力
  - `6`: 商会ランク
  - `7`: 商会貢献度
- `dir`: ソート順を指定します。
  - `0`: 昇順
  - `1`: 降順
- `log`: `false` を指定すると、UI 上のタグクラウドに検索履歴が反映されません。

#### 戻り値

- `status`: 検索に成功した場合は `true`
- `params`: リクエスト時の引数。URI に含まれるワールド名なども返します。
- `request_uri`: リクエストした URI のパス以降
- `item_count`: アイテムの総件数
- `returned_item_count`: 今回のリクエストで返した件数。現時点では WebAPI でのページングを実装していないため、常に `item_count` と同じ件数となります。
- `items`: 検索結果を配列で返します。
  - `town`: 商会が存在する街を文字列で返します。
  - `company_id`: 商会ショップ検索で内部的に採番した商会 ID。たまに更新されるため、不変ではありません。
  - `company`: 商会名
  - `member`: 商会員数
  - `contribution`: 商会貢献度
  - `item`: アイテム名
  - `maxlife`: 最大耐久
  - `item_id`: 商会ショップ検索で内部的に採番したアイテム ID。@Web で初めて登場した際に採番されます。
  - `goods_id`: 出品されている「その」陳列商品の内部 ID。各商会で陳列されている一商品ごとに採番されます。また、クローリングのたびに更新されます。
  - `net`: 数量
  - `price`: 出品価格
  - `cost`: 原価
  - `life`: 現在の耐久
  - `power`: 貫通
  - `atk`: 攻撃力
  - `def`: 防御力
  - `update_date`: 取得日時。ISO 8601 で返しますが、常に GMT+09:00 で返します。
  - `average`: 現在出品中の平均価格。クローリング最終段階で更新されるため、クローリング中は正しい値とは限りません。
  - `highest`: 現在出品中の最高価格。同上。
  - `lowest`: 現在出品中の最低価格。同上。
  - `description`: アイテム説明
  - `sex`: 装備品の場合、性別制限を数値で格納します。
  - `boost`: ブースト効果。「`[ブースト対象のスキル]+[ブースト値]`」で格納されます。複数ある場合は `, ` (半角カンマ + 半角スペース) で結合されます。
  - `world`: ワールド名。`Astraios` または `Eos` が格納されます。

#### 呼び出し例

- `https://search.meixiaojie.com/api/v1/search/all/0/C2`
  - 仕入発注書(カテゴリー2)を検索します。
- `https://search.meixiaojie.com/api/v1/search/astraios/2,6/%E3%82%AB%E3%83%AD`
  - Astraios リスボンおよびロンドンで「カロ」を含むアイテムを検索します。
- `https://search.meixiaojie.com/api/v1/search/all/0/%E5%90%8D%E5%8C%A0%E3%82%AB%E3%83%AD%E3%83%8D%E3%83%BC%E3%83%89%E7%A0%B216%E9%96%80?price_to=1500000&log=false`
  - 1,500,000 D 以下の名匠カロネード砲16門を検索し、かつタグクラウドには反映させないようにします。
- `https://search.meixiaojie.com/api/v1/search/all/-/Puca?log=false`
  - 「Puca」を含む商会名の出品を検索し、かつタグクラウドには反映させないようにします。
- `https://search.meixiaojie.com/api/v1/search/astraios/-/Puca%E2%85%B9Puca?conj=2&log=false`
  - Astraios ワールドの「PucaⅹPuca」商会の陳列物をすべて表示し、かつタグクラウドには反映させないようにします。

#### 注意点

- 検索クエリに対して 30 種類以上の商品が存在する場合、検索を中断して `status` に `false` を格納します。この場合は検索条件を見直した上で再度リクエストしてください。
  - エラーとなる例:
    - 「砲」
- 「金」を検索する場合は上記制限対象となりますので、必ず `conj=2` を指定してください。

### 検索対象候補の取得

#### エンドポイント

```
https://search.meixiaojie.com/api/v1/labels/candidates/[種類]/[クエリ]
```

#### 引数

- 種類
  - 以下文字列を与えます。
    - `items`: アイテム名を検索
    - `companies`: 商会名を検索
    - `boost`: ブーストで検索
- クエリ
  - 検索対象の文字列。必ず URL エンコードしてください。
- クエリストリング:
  - `conj`: 検索時の結合条件を指定します。
    - `0`: 半角スペースで区切ったキーワードのいずれかを含む
    - `1`: 半角スペースで区切ったキーワードすべてを含む
    - `2`: 完全一致

#### 戻り値

- `status`: 検索に成功した場合は `true`
- `params`: リクエスト時の引数。URI に含まれるワールド名なども返します。
- `request_uri`: リクエストした URI のパス以降
- `candidates`: 検索対象候補を最大 20 件配列に格納します。
- `ids`: 検索対象候補を最大 20 件、ハッシュ形式で格納します。キーは商会ショップ検索内部のID、値は検索対象候補です。

### 価格推移情報の取得

#### エンドポイント

```
https://search.meixiaojie.com/api/v1/histories/[ワールド名]/items/[アイテムID]
```

#### 引数

- ワールド名:
  - 以下文字列を与えます。
    - `all`: すべてのワールド
    - `astraios`: Astraios のみ
    - `eos`: Eos のみ
- アイテム ID:
  - ショップ検索機能または検索対象候補の取得で取得できる、商会ショップ検索内部のアイテム ID を指定します。

#### 戻り値

- `status`: 取得に成功した場合は `true`
- `params`: リクエスト時の引数。URI に含まれるワールド名なども返します。
- `request_uri`: リクエストした URI のパス以降
- `histories`: 直近 100 件の価格推移を配列で返します。
  - `average`: その時点での平均価格
  - `lowest`: その時点での最低価格
  - `highest`: その時点での最高価格
  - `create_date`: 取得日時。ISO 8601 で返しますが、常に GMT+09:00 で返します。

#### 呼び出し例

- `https://search.meixiaojie.com/api/v1/histories/astraios/items/132`
  - 2017/09/11 時点でのマグロのオリーブステーキの価格推移を返します。
    - アイテム ID は変更されている可能性がありますので、必ず呼び出し直前に検索してください。

### ワールド情報の取得

#### エンドポイント

```
https://search.meixiaojie.com/api/v1/statistics
```

#### 引数

なし

#### 戻り値

- `status`: 常に `true`
- `request_uri`: リクエストした URI のパス以降
- `worlds`: ワールド情報を配列で格納します。
  - `world`: ワールド名。`Astraios` または `Eos` が格納されます。
  - `num_of_chars`: 総キャラクタ数
  - `num_of_companies`: 商会数
  - `create_date`: 集計日時。ISO 8601 で返しますが、常に GMT+09:00 で返します。

### 同盟港変動情報の取得

#### エンドポイント

```
https://search.meixiaojie.com/api/v1/ally
```

#### 引数

なし

#### 戻り値

- `status`: 常に `true`
- `request_uri`: リクエストした URI のパス以降
- `changed`: 変動情報を値をハッシュとする配列で返します。
  - `world`: ワールド名。`Astraios` または `Eos` が格納されます。
  - `name`: 変動した同盟港名。
  - `changed_from`: 変動前の国名。
  - `changed_to`: 変動後の国名。
  - `create_date`: 変動を検知した日時。ISO 8601 で返しますが、常に GMT+09:00 で返します。

### 都市名→都市IDテーブル取得

#### エンドポイント

```
https://search.meixiaojie.com/api/v1/labels/towns
```

#### 引数

なし

#### 戻り値

- `status`: 常に `true`
- `request_uri`: リクエストした URI のパス以降
- `towns`: 街一覧をハッシュ形式で返します。キーは @Web における街 ID、値は対応する街名です。


## 注意など

- 将来の仕様変更に伴い、v1 を廃止する場合があります。
- 歴史的経緯でパラメータは 0 スタートになっているケースと 1 スタートになっているケースがあるのでご注意ください。
- 同じく歴史的経緯で、パラメータ名と戻り値のキーが一致しない場合があります。
- WebAPI は原則として以下用途のみの提供となります。
  - 個人的利用など限られた範囲での利用。限られた範囲には以下を含みます。
    - 限られた友人間での利用。
    - 商会サイトにショップ陳列物を表示するだけの用途。
- サーバメンテナンス等の予告は Twitter アカウント @dol_allies で行っていますが、予告なしのメンテナンスを行う場合があります。
- 商会ショップ検索本体は外形死活監視を実施していますが、WebAPI は一部を除き監視していません。そのため、動作を保証するものではありません。
- WebAPI は公開機能ではありませんので、本ドキュメントの再配布は原則としてご遠慮ください。
- WebAPI は商会ショップ検索と比較すると枯れていないため、バグがある可能性があります。バグがあった場合は Twitter @dol_allies までご連絡いただければ対応します。