くまポンAPI(beta)について

くまポンAPI(beta)について
1.エリア一覧取得API
2.クーポンデータ取得API

くまポンAPI(beta)について

くまポンAPI(beta)とは？

「くまポンbyGMO」では、掲載されているクーポンの情報などの一部をhttps経由で得ることができるAPIを提供しております。毎日更新される多彩なクーポンの情報を、サイト・WEBサービスのコンテンツとしてご活用いただけます。

API仕様

各情報に対応するURLをリクエストすることで、XML,JSON,JSONPなどの形式でレスポンスを得ることができます（UTF-8エンコード）。データの詳細な形式等については、各APIの資料をご参照ください。

くまポンAPI(beta)ご利用上の注意点

API利用登録などの手続きは不要で、どなたでもご使用になれます。
APIの仕様、およびご利用方法については本ページの各APIについての仕様をご参照ください。
本APIによって得られる情報は、リアルタイムな情報となっています。「くまポンbyGMO」で販売されるクーポンは毎日追加・更新され、また販売状況によって残り枚数などの情報が随時変動するため、本APIを利用した情報の表示を行うサービスにおいては、可能な限り最新の情報を取得したうえで表示を行っていただくようお願いいたします。
本APIを通して得られた情報について、データを正しくない情報に改変した上で公開することはできません。また、同じく本APIを通して得られた情報について、これを販売するなどの二次的な利用を行うことはできません。
また、サーバーに負荷のかかる高頻度のアクセス等、弊社が適当でないと認める使用が行われていると判断した場合には、予告無くAPIの停止、制限、または仕様の変更を行う場合がございます。

免責事項

本APIは現在ベータ版（試験運用版）です。
本APIはその動作について予告無く仕様の変更または停止行う場合があります。そのような仕様の変更または停止があった場合を含め、本APIを直接に利用したことによって生じたいかなる損害についても、「くまポンbyGMO」の運営会社であるGMOビューティー株式会社はその責任を負いかねます。
また、本APIから得られる情報に基づいてサービス・情報を公開したことによる損害、またはそれらの公開されたサービス・情報を利用またはダウンロードしたことによって利用者に生じたいかなる損害についても、同様に責任を負いかねます。

更新履歴

[2023/06/22]

エリア一覧取得APIの仕様を変更しました。

[2020/01/20]

通信プロコトルの一部をhttps経由で取得できるように変更しました。

[2014/06/16]

クーポンの総在庫数を削除しました。
クーポンデータ取得API レスポンスデータからタグを削除しました。

[2014/02/25]

ジャンルを追加しました。
クーポンデータ取得APIにタグを追加しました。

[2012/01/18]

画像サイズを追加しました。
クーポンデータ取得APIにタグを追加しました。

[2011/01/28]

ベータ版（試験運用版）リリース。
エリア一覧取得APIが利用可能になりました。
クーポンデータ取得APIが利用可能になりました。

1.エリア一覧取得API
くまポン(https://kumapon.jp/)で現在購入可能なクーポンが販売されているエリアグループ（都道府県）の一覧情報を取得できます。

リクエストURL（すべてのエリアグループの情報を得るとき）

https://api.kumapon.jp/area_groups.(拡張子)?callback=[コールバック関数名]

リクエストURL（ある1つのエリアグループの情報だけを得るとき）

https://api.kumapon.jp/area_groups/（エリアグループの番号）.(拡張子)?callback=[コールバック関数名]

リクエストパラメータ

パラメータ	値	省略	説明
(エリアグループの番号)	整数値	可	このAPIのレスポンスにおけるgroup（エリアグループの番号）の値を指定することで、そのエリアグループの情報のみを得ることができます。
(拡張子)	xml または json	不可	取得するデータのフォーマットを指定します。
callback	任意の値	可	拡張子がjsonである場合、このパラメータを指定するとjsonpデータが得られます。指定したパラメータの値がjsonpの関数名となります。

レスポンスデータ

レスポンスは、エリアグループ情報のレコードが1つ〜複数含まれたものが取得できます。
データ中の記号、および全角文字はすべてエンティティ化(xmlの場合)、または\uXXXX (UTF-16) エンコード(jsonの場合)されています。

キー	値	説明
area_groups	Array	配下ノードに複数のarea_groupデータを持ちます。 (JSON/JSONP形式では出力されません)
area	Array	配下ノードにエリア情報の各項目を持ちます。 (JSON/JSONP形式では出力されず、area情報自体が配列に格納されます)
name	文字列	エリアグループの日本語名称です。
id	整数値	エリアグループ固有の番号です。
version	文字列	APIのバージョンです。 (例：20110128)
deals	Array	配下ノードに複数のdealデータを持ちます。 (JSON/JSONP形式では、販売されるクーポン（商品）の番号の配列が出力されます)
deal	整数値	販売されるクーポン（商品）固有の番号です。 (JSON/JSONP形式では出力されません)

レスポンスデータの例(XML)

URL	https://api.kumapon.jp/area_groups.xml
<?xml version="1.0" encoding="UTF-8"?> <area_groups type="array"> <area_group> <name>埼玉県</name> <version>20110128</version> <id>21</id> <deals type="array"> <deal type="integer">237</deal> <deal type="integer">239</deal> </deals> </area_group> <area_group> <name>千葉県</name> <version>20110128</version> <id>23</id> <deals type="array"> <deal type="integer">237</deal> <deal type="integer">239</deal> </deals> </area_group> <area_group> <name>新宿駅周辺</name> <version>20110128</version> <id>25</id> <deals type="array"> <deal type="integer">239</deal> </deals> </area_group> <area_group> <name>神奈川県</name> <version>20110128</version> <id>27</id> <deals type="array"> <deal type="integer">237</deal> <deal type="integer">239</deal> </deals> </area_group> <area_group> <name>上野駅周๟</name> <version>20110128</version> <id>95</id> <deals type="array"> <deal type="integer">237</deal> </deals> </area_group> </area_groups>

URL

https://api.kumapon.jp/area_groups.xml

<?xml version="1.0" encoding="UTF-8"?>
<area_groups type="array">
  <area_group>
    <name>&#22524;&#29577;&#30476;</name>
    <version>20110128</version>
    <id>21</id>
    <deals type="array">
      <deal type="integer">237</deal>
      <deal type="integer">239</deal>
    </deals>
  </area_group>
  <area_group>
    <name>&#21315;&#33865;&#30476;</name>
    <version>20110128</version>
    <id>23</id>
    <deals type="array">
      <deal type="integer">237</deal>
      <deal type="integer">239</deal>
    </deals>
  </area_group>
  <area_group>
    <name>&#26032;&#23487;&#39365;&#21608;&#36794;</name>
    <version>20110128</version>
    <id>25</id>
    <deals type="array">
      <deal type="integer">239</deal>
    </deals>
  </area_group>
  <area_group>
    <name>&#31070;&#22856;&#24029;&#30476;</name>
    <version>20110128</version>
    <id>27</id>
    <deals type="array">
      <deal type="integer">237</deal>
      <deal type="integer">239</deal>
    </deals>
  </area_group>
  <area_group>
    <name>&#19978;&#37326;&#39365;&#21608;&#3679;</name>
    <version>20110128</version>
    <id>95</id>
    <deals type="array">
      <deal type="integer">237</deal>
    </deals>
  </area_group>
</area_groups>

レスポンスデータの例(JSON)

URL	https://api.kumapon.jp/area_groups.json
[ {"name":"\u57fc\u7389\u770c","id":"21","deals":[3,42,50,4,52,51,43]}, {"name":"\u57fc\u7389\u770c","id":"23","deals":[3,42,50,4,52,51,43]}, {"name":"\u5343\u8449\u770c","id":"25","deals":[3,42,50,4,52,51,43]} ]

URL

https://api.kumapon.jp/area_groups.json

[
{"name":"\u57fc\u7389\u770c","id":"21","deals":[3,42,50,4,52,51,43]},
{"name":"\u57fc\u7389\u770c","id":"23","deals":[3,42,50,4,52,51,43]},
{"name":"\u5343\u8449\u770c","id":"25","deals":[3,42,50,4,52,51,43]}
]

2.クーポンデータ取得API
クーポン番号を指定して、販売されているクーポンの詳細情報を取得できます。

リクエストURL

https://api.kumapon.jp/deals/(クーポン番号).(拡張子)

リクエストパラメータ

パラメータ	値	省略	説明
(クーポン番号)	整数	不可	クーポン（商品）ごとに一意な番号を指定。エリア一覧取得APIなどで得られる。
(拡張子)	xml または json	不可	取得するデータのフォーマットを指定します。

レスポンスデータ

レスポンスは、1つのクーポンの情報であり、以下の情報を持ちます。
データ中の記号、および全角文字はすべてエンティティ化(xmlの場合)、または\uXXXX (UTF-16) エンコード(jsonの場合)されています。

キー	値	説明
title	文字列	クーポンのタイトルです。
images	Array	配下ノードに複数の商品画像情報（image）を持ちます。
image	Array	配下ノードに商品画像情報の各項目(max,large,small,thumb)を持ちます。
max	文字列	大サイズ(400×267pixel)の商品画像のURLです。
large	文字列	大サイズ(660×440pixel)の商品画像のURLです。
small	文字列	通常サイズ(218×138pixel)の商品画像のURLです。
thumb	文字列	サムネイルサイズ(95×63pixel)の商品画像のURLです。
start	日付時刻	クーポンの販売開始日時です。
expire	日付時刻	クーポンの販売終了日時です。
coupon_start	日付時刻	購入したクーポンが利用可能になる日時です。
coupon_expire	日付時刻	クーポンの利用期限です。（例：2011-04-30T23:59:59+09:00）
subtitle	文字列	クーポンのサブタイトルです。
regular_price	整数値	クーポンの参考価格（割引前の価格）です。
price	文字列	販売価格です。
buy_cnt	整数値	購入された枚数です。
buy_limit	整数値	購入可能な上限枚数です。
buyable	YES/NO	このクーポンが現在購入可能かどうかを示します。 YES:販売中 NO:販売終了
url	文字列	クーポン販売ページのURLです。
twitter_url	文字列	Xでのツイート用URLです。このリンクを使って、クーポンについてツイートすることができます。
facebook_url	文字列	Facebookでのシェア用URLです。 (例:http://www.facebook.com/sharer.php?u=https%3A%2F%2Fkumapon.jp%2Fdeals%2Ftkyw20110120g)
permalink	文字列	クーポン毎に固有の文字列で、https://kumapon.jp/deals/ の後に続けることで、クーポン販売ページのURLとなります。
shop_lat	数値	店舗所在地座標の緯度です。（空白の場合もあります）
shop_lng	数値	店舗所在地座標の経度です。（空白の場合もあります）
recommend	文字列	「ショップ情報＆スタッフの声」です。
michelin	整数値	店舗のミシュラン格付けを示します。 3:ミシュラン三つ星店舗 2:ミシュラン二つ星店舗 1:ミシュラン一つ星店舗 0:上記以外
shop_name	文字列	店舗名です。
shop_zip	文字列	店舗所在地の郵便番号です。 (例:150-0001)
shop_address	文字列	店舗所在地の住所です。市区町村と番地以降の間に改行(<br/>)が入ります。
shop_tel	文字列	店舗の連絡先です。
shop_hours	文字列	店舗の営業時間です。
shop_map_url	文字列	店舗所在地を示したGoogleMapのURLです。
shop_url	文字列	店舗のホームページURLです。
notes	Array	配下ノードに複数のnoteデータを持ちます。 (JSON/JSONP形式では、クーポンについての詳細情報（最大3つ）の配列が出力されます)
note	文字列	クーポンについての詳細情報です。 (JSON/JSONP形式では、出力されません)
point_rate	数値	クーポン購入時の支払い価格に対して,この率をかけたGMOポイントを付与します。（単位：％）
spec	文字列	クーポンの利用条件です。
mail_title	文字列	商品紹介メール題名に使用される文言です。
mail_description	文字列	商品紹介メールの中で使用される、最大190文字のアピール文言です。
version	文字列	APIのバージョンです。 (例：20110128)
buy_min	整数値	クーポンの購入成立枚数です。総売上枚数がこれを下回るとき、クーポンは成立しません。
tags	文字列	クーポンのタグです。
genre	文字列	クーポンのジャンルを示します。 beauty: ビューティー campaign: キャンペーン delivery: 通販 etc: その他 gourmet: グルメ hairsalon: ヘアサロン leisure: レジャー lesson: レッスン massage: リラクゼーション present: プレゼント shopping: ショッピング syukuhaku: 宿泊 nail: ネイルサロン eyebeauty: まつげサロン este: エステ beautyclinic: 美容クリニック dental: 審美歯科