hotpepper-gourmet-tddschn

About

Fork of hotpepper-gourmet package on pypi (https://github.com/paperlefthand/hotpepper-gourmet) that uses https instead of http.

ホットペッパーグルメAPIのシンプルなクライアントライブラリです

API Coverage

This library now covers all official Hotpepper Gourmet endpoints (12/12).

API (Official)	Python method (sync / async)
Gourmet Search	search / search_async
Shop Name Search	name_search / name_search_async
Budget Master	budget_master / budget_master_async
Large Service Area Master	large_service_area_master / large_service_area_master_async
Service Area Master	service_area_master / service_area_master_async
Large Area Master	large_area_master / large_area_master_async
Middle Area Master	middle_area_master / middle_area_master_async
Small Area Master	small_area_master / small_area_master_async
Genre Master	genre_master / genre_master_async
Credit Card Master	credit_card_master / credit_card_master_async
Special Master	special_master / special_master_async
Special Category Master	special_category_master / special_category_master_async

Language Notation (Japan topics)

In this project, when we reference Japan-related proper nouns or useful markers, we include:

• Japanese + Romaji (e.g., 東京, Tōkyō)
• zh_TW for kana terms (e.g., グルメ, gurume, 美食)
• Original language for katakana transliterations (e.g., ホットペッパー, Hotto Peppaa, Hot Pepper)

Examples:

• 東京 (とうきょう, Tōkyō, 東京)
• 新宿 (しんじゅく, Shinjuku, 新宿)
• ラーメン (raamen, 拉麵, ramen)
• ジャンル (janru, 類型, genre)

How To Use

keyidの取得

ホットペッパーグルメAPIに登録し, token(keyid)を取得

CLI利用時は環境変数 HOTPEPPER_API_KEY を使用します:

export HOTPEPPER_API_KEY="YOUR_KEYID"

サンプルコード

同期版

>>> from pygourmet import Api, Option
>>> api = Api(keyid=YOUR_KEYID)
>>> option = Option(lat=35.170915, lng=136.8793482, keyword="ラーメン", range=4, count=3)
>>> shops = api.search(option)
>>> len(shops)
3
>>> shops[0].name
'shop name'

複数値クエリと拡張レスポンス (type=special+credit_card) の例:

from pygourmet import Api, Option

api = Api(keyid="YOUR_KEYID")
option = Option(
    keyword="焼肉",
    large_area=["Z011", "Z012"],
    budget=["B001", "B002"],
    type=["special", "credit_card"],
)

shops = api.search(option)
first = shops[0]

# `type=special+credit_card` を指定した場合もモデルで取得可能
if first.special:
    print(first.special[0].name)
if first.credit_card:
    print(first.credit_card[0].name)

マスタAPIの例（ジャンル + 大エリア）:

from pygourmet import Api, GenreMasterOption, LargeAreaMasterOption

api = Api(keyid="YOUR_KEYID")

genres = api.genre_master(GenreMasterOption(keyword="居酒屋"))
areas = api.large_area_master(LargeAreaMasterOption(keyword="東京"))

print(genres[0].code, genres[0].name)
print(areas[0].code, areas[0].name)

非同期版

async def call_search_async():
    shops = await api.search_async(option=option)
    print(len(shops))

loop = asyncio.get_event_loop()
loop.run_until_complete(call_search_async())

CLI: hotpepper-cli

インストール後は hotpepper-cli コマンドが利用できます.

グルメ検索（東京 / とうきょう / Tōkyō / 東京）:

hotpepper-cli search --keyword "ラーメン" --large-area Z011 --count 5

店名サーチ（新宿 / しんじゅく / Shinjuku / 新宿）:

hotpepper-cli name-search --keyword 新宿 --count 10

ジャンルマスタ取得（JSON出力）:

hotpepper-cli -j genre --keyword 居酒屋

特集カテゴリ取得:

hotpepper-cli special-category

補足:

• -j, --json: JSONを標準出力
• 省略時は Rich テーブルで整形表示
• APIキーは --api-key で直接指定も可能

開発者向けガイド

このリポジトリは uv によるパッケージ管理を採用しています. Python バージョンは 3.12, 3.13, 3.14 をサポート対象としています.

セットアップ

# 依存関係のインストール（開発環境構築）
uv sync

よく使うコマンド

原則として uv run を介して実行します.

# テスト実行
uv run pytest -v

# 統合テスト実行（要 HOTPEPPER_KEYID 環境変数）
# ローカル環境でのみ実行し、APIキーを利用して実際にリクエストを送ります
uv run pytest --run-integration

# 静的型チェック
uv run ty check

# Lint チェック
uv run ruff check .

# コードフォーマット適用
uv run ruff format .

# コミット前チェック（Lint/Format/TypeCheck 等を一括実行）
uv run prek

# API ドキュメント生成
uv run pdoc src/pygourmet

# 特定バージョンの動作確認（tox）
uv run tox -e py314

コーディング規約

• Style: Ruff 準拠 (4スペースインデント, ダブルクォート, スネークケース). クラス名は PascalCase.
• Docstring: Google Style.
• Type: Pydantic v2 を活用し, Any を排除した厳格な型注釈を行う.

テストガイドライン

• 基本: pytest + pytest-httpx (モック).
• 統合テスト: @pytest.mark.integration を付与. uv run pytest --run-integration でのみ実行される.
• 非同期: pytest-asyncio を使用.

コミット・PRガイドライン

• コミットメッセージは Conventional Commits 形式.
• コミット前に必ず uv run prek をパスさせること.
• PR には変更の目的, テスト結果, ドキュメント更新の有無を記載.

CI/CD

• CI: GitHub Actions + tox-uv (Python 3.12, 3.13, 3.14).
• TestPyPI: dev ブランチへの push で自動デプロイ.
• PyPI / Docs: v* タグ (例: v1.0.0) の push で本番リリースおよび GitHub Pages 更新.

セキュリティ

• API Key (HOTPEPPER_KEYID) は絶対コミットしない.
• ローカル開発では .env を利用する (python-dotenv 対応).

---

Powered by ホットペッパー Webサービス