Cheap Gas Nearby

What this skill does

ユーザーが提供した現在位置を基準に、近くで最も安い給油所を見つけてくれる。

• 位置は自動的に推定しない。
• 必ず最初に現在位置を質問する。
• 価格データは韓国石油公社のOpinet公式APIを優先的に使用する。
• 地域名/駅名/ランドマーク入力は Kakao Map anchor 検索で座標を確定した後、Opinet nearby 検索に接続する。
• デフォルト製品は**ガソリン(B027)で、ユーザーが軽油と明示すれば軽油(D047)**に変更する。

When to use

• "近くで最も安い給油所を探して"
• "ソウル駅の近くでガソリンが最も安いところはどこ?"
• "江南で軽油が安い給油所を数か所教えて"
• "ここの近くでセルフ給油所の中で安い順に教えて"

Mandatory first question

位置情報なしで直ちに検索してはいけない。必ず最初に質問する。

• 推奨質問: 現在位置を教えてください。地域名/駅名/ランドマーク/緯度・経度のいずれか、ご都合の良い形式で送っていただければ、近くで最も安い給油所を探しますね。
• 製品が不明確な場合: ガソリン基準で見ましょうか、軽油基準で見ましょうか? 特に指定がなければガソリンで探しますね。
• 位置が曖昧な場合: 最寄りの駅名または動名をもう一度教えてください。

Default path

基本的に https://k-skill-proxy.nomadamas.org/v1/opinet/around と /v1/opinet/detail を経由して照会する。ユーザー側が別途 OPINET_API_KEY を準備する必要はない。

Official Opinet surfaces

• オープンAPI案内: https://www.opinet.co.kr/user/custapi/openApiInfo.do
• 反径内給油所: https://www.opinet.co.kr/api/aroundAll.do
• 給油所詳細情報(ID): https://www.opinet.co.kr/api/detailById.do
• 地域コード: https://www.opinet.co.kr/api/areaCode.do

反径検索の主要パラメータ:

• x, y: 基準位置のKATEC座標
• radius: 反径(m、最大 5000)
• prodcd: B027(ガソリン)、D047(軽油)、B034(プレミアムガソリン)、C004(灯油)、K015(LPG)
• sort=1: 価格順

Location resolution surface

• Kakao Map モバイル検索: https://m.map.kakao.com/actions/searchView?q=<query>
• Kakao Map 場所パネル JSON: https://place-api.map.kakao.com/places/panel3/<confirmId>

位置文字列は Kakao Map でanchor座標(WGS84)を取得した後、内部的にWGS84 → KATEC変換を適用して Opinet aroundAll.do に渡す。

Workflow

1. ユーザーに必ず現在位置を質問する。
2. 位置文字列を受け取ったら Kakao Map anchor 検索で座標を見つける。
   • 緯度/経度を直接受け取った場合は anchor 検索をスキップする。
3. 座標を KATEC に変換する。
4. Opinet aroundAll.do を sort=1 価格順で照会する。
5. 上位候補に対して detailById.do を呼び出し、道路名住所、電話番号、セルフ有無、洗車場、簡易整備、品質認証有無を補強する。
6. 通常は3～5件だけ短くまとめる。

Responding

結果は通常、以下のフィールドを含めて短くまとめる。

• 給油所名
• 価格(ガソリン/軽油のうち要求された製品)
• 距離
• 住所
• セルフ有無
• 洗車場/簡易整備/品質認証有無(あれば)

Node.js example

const { searchCheapGasStationsByLocationQuery } = require("cheap-gas-nearby");

async function main() {
  const result = await searchCheapGasStationsByLocationQuery("서울역", {
    productCode: "B027",
    radius: 1000,
    limit: 3
  });

  console.log(result.anchor);
  console.log(result.items);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Done when

• ユーザーの現在位置を最初に確認した。
• デフォルトプロキシ経由で Opinet データを照会した。
• 公式 Opinet nearby 結果を最低1件以上見つけたか、見つからない理由と次の質問を提示した。
• 価格順上位結果を3～5件以内にまとめた。

Failure modes

• プロキシサーバーがダウンしているか、OPINET_API_KEY がサーバーに設定されていない場合。
• Kakao Map anchor が曖昧な場合、座標が正しく取得されない可能性があり、追加の位置確認が必要である。
• Opinet Open API レスポンスが一時的に空であったり、更新中である可能性がある。