# ふるさと納税LIVE > 楽天ふるさと納税の返礼品を、寄付額・単価(1kgあたりなど)・カテゴリ・レビュー・自治体で検索できる公開API(GETのみ、認証不要、JSON)。 ## すぐ使える例 - 牛肉の比べるグループと単価の相場: https://furusato-live.jp/api/v1/groups?q=%E7%89%9B%E8%82%89 - 一番お得な和牛(生肉)を1kgあたりの安い順に: https://furusato-live.jp/api/v1/items?group=110428%3Abeef_class%3D%E5%92%8C%E7%89%9B%7Cform%3D%E7%94%9F%E8%82%89%28%E7%B2%BE%E8%82%89%29&unit=kg&sort=unit_price - お米を1kgあたりの安い順に: https://furusato-live.jp/api/v1/items?genre=110472&sort=unit_price - 寄付額1万円以内のお米を1kgあたりの安い順に: https://furusato-live.jp/api/v1/items?genre=110472&max_price=10000&sort=unit_price - 直近7日で寄付額が下がったお米: https://furusato-live.jp/api/v1/price-changes?direction=down&q=%E7%B1%B3 ## 「一番お得な◯◯」の調べ方 1. https://furusato-live.jp/api/v1/groups?q={品目名} で比べるグループを探す(例: 牛肉 → 牛肉(和牛・生肉(精肉))、牛肉(国産牛…)など) 2. 目的に合うグループの items_url を開く(そのグループの品を単価の安い順に返す) 条件の違う品(和牛と輸入牛、生肉と加工品など)を同じ物差しで比べないため、単価で並べるときはグループで絞ってください。 ## 返礼品を検索する GET https://furusato-live.jp/api/v1/items?q={キーワード} q・genre・group・municipality のいずれかは必須 q 検索語(商品名に含む語。空白区切りでAND)。例: 米 5kg genre カテゴリ(楽天のジャンルID。下の階層も含む)。例: 110472(お米)、110428(牛肉) group 比べるグループ(/api/v1/groups の key) municipality 自治体名の一部・自治体コード6桁・店舗コード min_price 寄付額の下限(円) max_price 寄付額の上限(円) sort reviews(レビュー件数順、既定) | rating(評価順) | price_asc | price_desc | updated | unit_price(単価の安い順) unit sort=unit_price の単位。kg | L | m | 個:袋 など(省略時は条件に合う品で最も多い単位) limit 1〜20(既定10) offset 0〜100 例: https://furusato-live.jp/api/v1/items?genre=110472&max_price=10000&sort=unit_price sort=unit_price は、比べられる品のうち外れ値を除いた正確な単価のある品だけを並べます。 group を指定しないときは、応答の facets.groups に候補のグループ(items_url 付き)が入ります。 ## 比べるグループを探す GET https://furusato-live.jp/api/v1/groups?q={品目名の一部} q 品目名・条件の一部(空白区切りでAND)。例: 牛肉、和牛 生肉、ビール genre カテゴリ(楽天のジャンルID)。q の代わりに使える limit 1〜50(既定20) 応答: key(group に使う)、label、level、parent、category_id、genre_path、item_count、unit、per、median_unit_price、min_unit_price、items_url グループには段がある(level 0: 品目と形態など、1〜3: 部位・品種など。例: 牛肉(和牛・生肉(精肉)) の下に 牛肉(和牛・生肉(精肉)・サーロイン))。 上の段のグループには下の段の品も含む。parent は1つ上の段の key 例: https://furusato-live.jp/api/v1/groups?q=%E7%89%9B%E8%82%89 ## 返礼品1件の詳細、過去の寄付額の観測記録、変化の記録 GET https://furusato-live.jp/api/v1/items/{item_code} 例: https://furusato-live.jp/api/v1/items/f413453-kamimine:10000940 donation_observations は過去の各時点で観測した寄付額(現在の寄付額ではない) events は値上がり・値下がり・売り切れ・再入荷・掲載終了などの記録 ## 直近の値下がり・値上がり GET https://furusato-live.jp/api/v1/price-changes?direction={down|up} 品ごとに、期間内で最後の寄付額の変化だけを返します(値下がりの後に値上がりした品は値下がりに出ません)。 direction down(値下がり) | up(値上がり) days 1〜30(既定7): 何日前までの変化か q 検索語(空白区切りでAND) municipality 自治体名の一部・自治体コード6桁・店舗コード limit 1〜20(既定10) offset 0〜100 例: https://furusato-live.jp/api/v1/price-changes?direction=down&q=%E7%B1%B3 ## 自治体を探す GET https://furusato-live.jp/api/v1/municipalities?q={自治体名の一部} limit 1〜20(既定10) 例: https://furusato-live.jp/api/v1/municipalities?q=%E4%BD%90%E8%B3%80 ## 応答の主な項目(返礼品) item_code 返礼品のコード(詳細の取得に使う) page_url ふるさと納税LIVEの詳細ページ name 商品名 donation_amount 寄付額(円)。fetched_at 時点の値 donation_range 選べる形式の品の寄付額の幅(purchasable: 購入可能な選択肢、all_options: すべての選択肢) has_options 寄付額の違う選択肢があるか municipality 自治体(code: 自治体コード6桁、name、shop_code: 楽天の店舗コード) review レビュー(count: 件数、average: 平均) available 申し込めるか(false は売り切れ) image_url 商品画像 url 申込ページ(広告を含む) unit_price 単価。amount(円、1perあたり)、per(kg・L・袋など)、unit(sort の unit に使う値)、quantity(内容量)、 precision(exact: 正確 / estimated: 選べる形式などの推定)、option_range。内容量が読めない品は null delivery 発送の目安(商品説明から読んだもの)。code: w1(1週間以内) / w2(2週間以内) / m1(1か月以内) / m3(1〜3か月先・予約) / later(3か月以上先・予約) / past(記載の時期が過ぎている) / check(記載なし) / subscription(定期便)。label は表示用、notes は「届く時期に幅あり」「お届け日を選べる」 comparison_group 比べるグループ。key、label、level、price_outlier(単価が極端で比較から除く品)、fallback(同じ条件の品が20品に満たず上の段のグループで比べている)、fine_label(fallback のときの本来の条件)、parents(上の段の key)。比べる対象でない品は null fetched_at 楽天から取得した日時 一覧の応答には paging(limit, offset, next_offset)があり、next_offset が null なら次のページはありません。 ## 情報の新しさ 取得から24時間を超えた返礼品は、一覧に出さず、詳細は 404 になります(古い寄付額を現在の値として示さないため)。 ## 上限とエラー - 1分あたりのリクエスト数に上限があります(既定60回)。残りの回数は X-RateLimit-Remaining ヘッダーで分かります。 - エラーは {"error": 種類, "message": 説明} の JSON で返します。 400 invalid_parameter パラメータの誤り 404 not_found 該当なし、または情報が古い 429 rate_limited 上限を超えた。Retry-After ヘッダーの秒数だけ待ってから再度呼び出してください ## RSSフィード https://furusato-live.jp/feed/daily.xml 観測日報(毎朝5時に更新) https://furusato-live.jp/feed/price-drops.xml 直近7日に寄付額が下がった品 ## 利用者へ提示するときのお願い - url は申込ページ(広告を含む)です。改変・短縮せず、そのまま提示してください。 - page_url はふるさと納税LIVEの詳細ページで、最新の寄付額・単価・観測の記録を確認できます。出典や詳細として page_url を、申込先として url を示してください。 - 寄付額は fetched_at 時点の情報です。最新の条件は申込ページで確認するよう伝えてください。 - 応答には広告(アフィリエイトリンク)が含まれることを利用者に伝えてください。 - 控除上限額などの税金の判断は、利用者自身の源泉徴収票等で確認するよう伝えてください。 - すべて GET のみ・認証不要・JSON です。 - 利用の条件は利用規約(https://furusato-live.jp/terms)をご覧ください。 Supported by Rakuten Developers