parking-lot-search

Parking Lot Search

功能介绍

根据用户提供的当前位置，查找附近的公营停车场。

• 不会自动推断用户位置。
• 必须先主动询问当前位置。
• 默认仅展示公营停车场。
• 数据源自韩国官方전국주차장정보표준데이터（全国停车场信息标准数据）Open API。
• 先通过 Kakao Map 搜索定位锚点（anchor）并获取坐标，再按距离从官方数据中筛选排序。
• 官方标准数据不包含实时车位、空余车位或预订状态，因此切勿向用户表达确定性结论。

适用场景

• “帮我找找附近的停车场”
• “光化门附近哪里有公营停车场？”
• “首尔站附近有免费停车场吗？”
• “给我发个离我现在位置最近的公营停车场地图链接”

首次交互必问

切勿在没有明确位置信息的情况下直接搜索，必须先询问用户位置。

推荐提问文案：

请告诉我您的当前位置。您可以发送街区/车站名/地标/经纬度等任意方便的形式，我会为您查找附近的公营停车场。

如果位置较模糊：

能否请您提供更具体的附近车站名或洞/街区名称？

官方接口与资源

• 标准数据说明：https://www.data.go.kr/data/15012896/standard.do
• Open API 说明：https://www.data.go.kr/data/15012896/openapi.do
• Open API endpoint：https://api.data.go.kr/openapi/tn_pubr_prkplce_info_api
• k-skill proxy：/v1/parking-lots/search
• Kakao Map 移动端搜索：https://m.map.kakao.com/actions/searchView?q=<query>
• Kakao Map 地点面板 JSON：https://place-api.map.kakao.com/places/panel3/<confirmId>

工作流程

1. 务必先向用户询问当前位置。
2. 拿到位置文本后，使用 Kakao Map 确定 anchor 候选并获取坐标。
3. 根据 anchor 地址提取 特别市/道 + 市/郡/区 地址提示（address hint）。
4. 通过 k-skill-proxy /v1/parking-lots/search 或 parking-lot-search 包查询官方停车场数据。
5. 通常精简整理 3~5 个结果，并附上地图链接。
6. 提示收费标准和运营时间时，须注明数据基准日期，并说明非实时动态。

回复格式

回复结果通常精简包含以下字段：

• 停车场名称
• 距离
• 公营/民营及路内/路外/附设类型
• 地址
• 运营日/运营时间
• 收费信息、基础费用、加收费用
• 车位数
• 电话号码/管理机构
• 数据基准日期
• 地图链接

Node.js 示例

const { searchNearbyParkingLotsByLocationQuery } = require("parking-lot-search");

async function main() {
  const result = await searchNearbyParkingLotsByLocationQuery("광화문", {
    limit: 3,
    radius: 1500
  });

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

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

모두의주차장（Modoodu Parking）支持状态

Issue #135 中曾提到接入 모두의주차장 的可能性，但 v1 版本仅基于官方公共数据构建。在确认取得官方授权或签订正式合作 API 协议之前，严禁调用 모두의주차장 的非官方 API 或进行数据爬取。

完成标准

• 已优先确认用户的当前位置。
• 基于官方数据找到了至少 1 个附近的停车场，或给出了未查找到的原因及下一步引导提问。
• 将最近的结果精简整理在 3~5 个以内。
• 必要时已向用户明确说明该数据不代表实时空车位或预订状态。