parking-lot-search基于 Data.go.kr 官方数据的韩国公共停车场检索指南【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill导读parking-lot-search是 k-skill 仓库packages/parking-lot-search中一个面向韩国场景的 Node.js 包它以韩国公共数据门户 Data.go.kr 的전국주차장정보표준데이터全国停车场信息标准数据Open API 为主要数据源通过Kakao Map 文本地点解析 → 官方停车数据坐标检索两段式流程把광화문这类自然语言地点查询解析为附近停车场列表。读完本文你将掌握它的设计原则、代理优先/直连两种调用模式、公开 API 全貌、各配置参数的含义与取值范围以及底层源码与测试是如何保证结果准确性的。设计原则先问位置绝不猜测该包把用户隐私与结果可用性放在首位使用原则明确写入 README.md不自动推断或追踪用户位置绝不允许通过 IP、定位接口等方式猜测当前位置必须先询问当前位置接受동네街区/역명站名/랜드마크地标/위도·경도经纬度等任一种格式再发起检索默认只返回 공영公共停车场除非调用方显式要求包含 민영民营地点文本先经 Kakao Map 场所搜索解析成坐标再在官方停车数据集上按距离检索不提供实时满员/余位/预约状态——官方标准数据中根本没有这些字段包不会编造。对应的 instruction.md 也要求 Agent 在拿到位置前禁止直接搜索并给出推荐提问语현재 위치를 알려주세요. 동네/역명/랜드마크/위도·경도 중 편한 형식으로 보내주시면 근처 공영주차장을 찾아볼게요.官方数据接口一览包内所有外部请求目标在源码 src/index.js 中被硬编码为常量同时也在 README 中列出方便核对数据口径用途URLData.go.kr 标准数据集说明https://www.data.go.kr/data/15012896/standard.doData.go.kr Open API 文档https://www.data.go.kr/data/15012896/openapi.doOpen API 端点https://api.data.go.kr/openapi/tn_pubr_prkplce_info_apik-skill 共享代理默认路径/v1/parking-lots/searchKakao Map 移动搜索https://m.map.kakao.com/actions/searchView?qqueryKakao Map 场所面板 JSONhttps://place-api.map.kakao.com/places/panel3/confirmId需要注意端点必须走 HTTPS。在 CHANGELOG.md 中记录了 0.1.2 版本的一次修复——Data.go.kr 强制 HTTPS 后旧版本使用的http://地址会触发 301 跳转导致基于 Nodefetch的客户端失败因此源码常量统一使用https://。代理优先模式开箱即用默认情况下包通过 k-skill 共享代理https://k-skill-proxy.nomadamas.org即源码中的DEFAULT_PROXY_BASE_URL完成检索调用方无需申请 Data.go.kr API Key。README 给出的最小可运行示例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; });返回值中result.anchor是解析出的地点锚点名称、地址、纬度/经度result.items是按距离升序排列的停车场列表。如需使用自己的代理服务可通过环境变量或选项参数二选一指定环境变量KSKILL_PROXY_BASE_URL选项参数proxyBaseUrl源码 resolveProxyBaseUrl 的优先级为options.proxyBaseUrl→process.env.KSKILL_PROXY_BASE_URL→ 内置默认值。代理模式下包会向${base}/v1/parking-lots/search发起请求并携带latitude、longitude、limit、radius、public_only等查询参数见 fetchProxyParkingLots。代理模式可以通过注入fetchImpl在测试中完全离线验证测试用例 index.test.js 用假fetchImpl断言了请求 URL 的 origin 指向默认代理、pathname 为/v1/parking-lots/search、address_hint正确携带。直连模式传入 Data.go.kr API Key当需要直连官方 API 时传入apiKey或设置环境变量DATA_GO_KR_API_KEY并开启useDirectApi: trueconst result await searchNearbyParkingLotsByLocationQuery(광화문, { apiKey: process.env.DATA_GO_KR_API_KEY, limit: 5, radius: 2000 });直连触发条件在 useDirectApi 中定义显式设置useDirectApi: true或直接提供了apiKey/serviceKey之一。API Key 的解析优先级为options.apiKey→options.serviceKey→process.env.DATA_GO_KR_API_KEY见 resolveApiKey。没有 API Key 且未启用直连时会自动回落到代理模式避免调用方因缺 Key 直接抛错。直连 URL 的构造细节直连请求由 buildOfficialParkingLotApiUrl 构造其支持的参数与约束如下参数说明默认值取值范围serviceKey/apiKeyData.go.kr 服务密钥必填——pageNo分页页码11 100000numOfRows每页行数10001 1000type响应格式固定为jsonjson—publicOnly是否只查 공영为真时写入prkplceSe공영true布尔parkingType停车场类型写入prkplceType如노외无字符串addressHint地址前缀提示写入rdnmadr可经addressField换字段无字符串参数在写入 URL 前会经过 normalizeBoundedInteger 的边界校验pageNo、numOfRows越界或非法时会抛出带范围的错误信息。测试 buildOfficialParkingLotApiUrl targets... 验证了prkplceSe공영、prkplceType노외、rdnmadr서울특별시 종로구等参数被正确写入。公开 API 全览包通过 src/index.js 导出的公开接口如下parseCoordinateQuery(locationQuery)— 识别위도, 경도格式输入返回{ latitude, longitude }或null正则见 parse.jsnormalizeParkingLotRows(payload, origin, options)— 将官方 API 原始响应标准化为停车场对象数组按距离排序并去重buildOfficialParkingLotApiUrl(options)— 构造官方 API URL直连模式的核心工具searchNearbyParkingLotsByCoordinates(options)— 直接按坐标检索附近停车场searchNearbyParkingLotsByLocationQuery(locationQuery, options)— 文本地点查询的高级入口自动判断是坐标还是 Kakao 锚点。其中searchNearbyParkingLotsByLocationQuery是实际工作流入口若查询字符串能被parseCoordinateQuery解析为坐标则直接进入坐标检索否则走 Kakao 锚点解析流程见下文。底层工作原理两段式解析链路第一步Kakao Map 锚点解析当用户给出광화문这类文本地点时包执行以下链路见 resolveAnchor请求https://m.map.kakao.com/actions/searchView?qquery获取搜索页 HTML用 parseSearchResultsHtml 正则提取search_item base列表项得到候选的id、名称、类别、地址、电话用 rankAnchorCandidates 对候选打分排序名称完全匹配 1000、名称含역后缀变体 950、前缀匹配 800、包含匹配 600、地址包含 120并对역/광장/공원等锚点类别加分、对주차장类结果减分、对非纯数字 id 减分最终按分数降序、韩语 locale 排序依次请求https://place-api.map.kakao.com/places/panel3/confirmId获取场所面板 JSON用 normalizeAnchorPanel 归一化为带latitude/longitude的锚点若某个候选的面板请求返回 4xx/5xx 且属于可恢复错误则跳过继续尝试下一个见 isRecoverablePlacePanelError全部候选都拿不到可用坐标时抛出No usable Kakao Map place panel was available for query。测试 searchNearbyParkingLotsByLocationQuery resolves a Kakao anchor... 完整验证了这一链路前两次调用分别命中searchView?q광화문与places/panel3/1001并断言锚点地址为 서울특별시 종로구 세종대로 172。第二步地址提示与官方数据检索拿到锚点坐标后包用 extractAddressHint 从锚点地址中提取前两个词如 서울특별시 종로구作为addressHint再把它作为rdnmadr前缀传给官方 API从而把全韩数据快速收敛到目标市/区随后在客户端完成距离过滤与排序。标准化函数 normalizeParkingLotRows 做了以下关键工作兼容多种响应结构getParkingItems依次识别response.body.items、body.items、items及items.item数组/单对象等形态按坐标过滤用哈弗辛公式haversineDistanceMeters地球半径 6371008.8 米计算每个停车场与锚点的直线距离剔除超过radius默认 2000 米的记录字段双语归一官方响应同时存在英文/韩文两种字段如prkplceNm/주차장명、prkcmprt/주차구획수统一映射为英文语义字段去重与排序以id::name::address::lat::lng为键去重最终按距离升序、名称韩语排序输出。每个标准化后的条目包含约 30 个字段覆盖名称、地址、距离、容量capacity、等级grade、隔日限行alternateDayEnforcement、运营日operatingDays、工作日/周六/公休日开放时间weekday/saturday/holiday、费用信息feeInfo、basicTime、basicCharge、addUnitTime、addUnitCharge、dailyTicketCharge、monthlyTicketCharge、支付方式paymentMethods、无障碍车位hasAccessibleParking、管理机关与电话、数据基准日期referenceDate以及 Kakao 地图跳转链接mapUrl形如https://map.kakao.com/link/map/name,lat,lng。测试 normalizeParkingLotRows keeps public parking metadata... 对夹具数据parking-api-response.json验证了上述映射如 광화문광장 공영주차장 被识别为 공영/노상、容量 20、工作日 09:00-21:00、无无障碍车位并生成了正确的mapUrl可以包含 민영 的用例 验证了publicOnly: false时会把 세종로 민영주차장 一并返回。此外夹具中一条坐标字段为空的记录会被自动过滤见normalizeParkingLotRows中对toNumber结果非有限值的判空。输入校验与边界约束searchNearbyParkingLotsByCoordinates对入参有严格校验见 index.jslatitude/longitude必须是有限数值否则抛出latitude and longitude must be finite numberslimit默认 5合法范围 1 50radius兼容旧参数maxDistanceMeters默认 2000合法范围 1 50000publicOnly支持布尔值以及0/false/n/no/민영포함等字符串归一见 normalizeBoolean。测试 searchNearbyParkingLotsByCoordinates validates inputs 逐一断言了这些错误分支确保非法参数在发起外部请求前就被拦截。모두의주차장Modu Parking集成状态README 明确回应了 Issue #135 提出的是否接入 모두의주차장问题当前版本不抓取、不调用任何非官方的 모두의주차장接口只有在出现经过批准、稳定且法律上可用的 API 契约后才会考虑接入。这一点也在 instruction.md 中被重申属于产品边界声明避免 Agent 误以为可以绕过官方数据源。运行环境与安装前提包的运行约束记录在 package.json 中Node.js 18依赖全局fetch源码中request函数会校验fetchImpl/global.fetch是否为函数通过 npm 安装后在任意 Node 项目中require(parking-lot-search)即可本地开发可用npm testnode --test与npm run lintnode --check验证包的正确性测试全部基于本地夹具test/fixtures/下的anchor-search.html、anchor-panel.json、parking-api-response.json与注入的假fetchImpl不发起任何真实外部请求因此可离线、稳定地复现核心逻辑。总结parking-lot-search的工程价值在于把自然语言地点 → 坐标 → 官方停车场数据这一复杂链路封装为两个高层函数默认代理模式让无 Key 用户开箱即用直连模式满足有 Data.go.kr API Key 的合规调用需求同时通过严格的参数校验、双语字段归一、距离排序去重和完整测试保证了输出结果的确定性。如需深入源码建议从 src/index.js 的主流程入口与 src/parse.js 的解析/标准化函数入手结合 test/index.test.js 中的端到端用例理解完整调用链。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 parking-lot-search：基于 Data.go.kr 官方数据的韩国公共停车场检索指南
parking-lot-search基于 Data.go.kr 官方数据的韩国公共停车场检索指南【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill导读parking-lot-search是 k-skill 仓库packages/parking-lot-search中一个面向韩国场景的 Node.js 包它以韩国公共数据门户 Data.go.kr 的전국주차장정보표준데이터全国停车场信息标准数据Open API 为主要数据源通过Kakao Map 文本地点解析 → 官方停车数据坐标检索两段式流程把광화문这类自然语言地点查询解析为附近停车场列表。读完本文你将掌握它的设计原则、代理优先/直连两种调用模式、公开 API 全貌、各配置参数的含义与取值范围以及底层源码与测试是如何保证结果准确性的。设计原则先问位置绝不猜测该包把用户隐私与结果可用性放在首位使用原则明确写入 README.md不自动推断或追踪用户位置绝不允许通过 IP、定位接口等方式猜测当前位置必须先询问当前位置接受동네街区/역명站名/랜드마크地标/위도·경도经纬度等任一种格式再发起检索默认只返回 공영公共停车场除非调用方显式要求包含 민영民营地点文本先经 Kakao Map 场所搜索解析成坐标再在官方停车数据集上按距离检索不提供实时满员/余位/预约状态——官方标准数据中根本没有这些字段包不会编造。对应的 instruction.md 也要求 Agent 在拿到位置前禁止直接搜索并给出推荐提问语현재 위치를 알려주세요. 동네/역명/랜드마크/위도·경도 중 편한 형식으로 보내주시면 근처 공영주차장을 찾아볼게요.官方数据接口一览包内所有外部请求目标在源码 src/index.js 中被硬编码为常量同时也在 README 中列出方便核对数据口径用途URLData.go.kr 标准数据集说明https://www.data.go.kr/data/15012896/standard.doData.go.kr Open API 文档https://www.data.go.kr/data/15012896/openapi.doOpen API 端点https://api.data.go.kr/openapi/tn_pubr_prkplce_info_apik-skill 共享代理默认路径/v1/parking-lots/searchKakao Map 移动搜索https://m.map.kakao.com/actions/searchView?qqueryKakao Map 场所面板 JSONhttps://place-api.map.kakao.com/places/panel3/confirmId需要注意端点必须走 HTTPS。在 CHANGELOG.md 中记录了 0.1.2 版本的一次修复——Data.go.kr 强制 HTTPS 后旧版本使用的http://地址会触发 301 跳转导致基于 Nodefetch的客户端失败因此源码常量统一使用https://。代理优先模式开箱即用默认情况下包通过 k-skill 共享代理https://k-skill-proxy.nomadamas.org即源码中的DEFAULT_PROXY_BASE_URL完成检索调用方无需申请 Data.go.kr API Key。README 给出的最小可运行示例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; });返回值中result.anchor是解析出的地点锚点名称、地址、纬度/经度result.items是按距离升序排列的停车场列表。如需使用自己的代理服务可通过环境变量或选项参数二选一指定环境变量KSKILL_PROXY_BASE_URL选项参数proxyBaseUrl源码 resolveProxyBaseUrl 的优先级为options.proxyBaseUrl→process.env.KSKILL_PROXY_BASE_URL→ 内置默认值。代理模式下包会向${base}/v1/parking-lots/search发起请求并携带latitude、longitude、limit、radius、public_only等查询参数见 fetchProxyParkingLots。代理模式可以通过注入fetchImpl在测试中完全离线验证测试用例 index.test.js 用假fetchImpl断言了请求 URL 的 origin 指向默认代理、pathname 为/v1/parking-lots/search、address_hint正确携带。直连模式传入 Data.go.kr API Key当需要直连官方 API 时传入apiKey或设置环境变量DATA_GO_KR_API_KEY并开启useDirectApi: trueconst result await searchNearbyParkingLotsByLocationQuery(광화문, { apiKey: process.env.DATA_GO_KR_API_KEY, limit: 5, radius: 2000 });直连触发条件在 useDirectApi 中定义显式设置useDirectApi: true或直接提供了apiKey/serviceKey之一。API Key 的解析优先级为options.apiKey→options.serviceKey→process.env.DATA_GO_KR_API_KEY见 resolveApiKey。没有 API Key 且未启用直连时会自动回落到代理模式避免调用方因缺 Key 直接抛错。直连 URL 的构造细节直连请求由 buildOfficialParkingLotApiUrl 构造其支持的参数与约束如下参数说明默认值取值范围serviceKey/apiKeyData.go.kr 服务密钥必填——pageNo分页页码11 100000numOfRows每页行数10001 1000type响应格式固定为jsonjson—publicOnly是否只查 공영为真时写入prkplceSe공영true布尔parkingType停车场类型写入prkplceType如노외无字符串addressHint地址前缀提示写入rdnmadr可经addressField换字段无字符串参数在写入 URL 前会经过 normalizeBoundedInteger 的边界校验pageNo、numOfRows越界或非法时会抛出带范围的错误信息。测试 buildOfficialParkingLotApiUrl targets... 验证了prkplceSe공영、prkplceType노외、rdnmadr서울특별시 종로구等参数被正确写入。公开 API 全览包通过 src/index.js 导出的公开接口如下parseCoordinateQuery(locationQuery)— 识别위도, 경도格式输入返回{ latitude, longitude }或null正则见 parse.jsnormalizeParkingLotRows(payload, origin, options)— 将官方 API 原始响应标准化为停车场对象数组按距离排序并去重buildOfficialParkingLotApiUrl(options)— 构造官方 API URL直连模式的核心工具searchNearbyParkingLotsByCoordinates(options)— 直接按坐标检索附近停车场searchNearbyParkingLotsByLocationQuery(locationQuery, options)— 文本地点查询的高级入口自动判断是坐标还是 Kakao 锚点。其中searchNearbyParkingLotsByLocationQuery是实际工作流入口若查询字符串能被parseCoordinateQuery解析为坐标则直接进入坐标检索否则走 Kakao 锚点解析流程见下文。底层工作原理两段式解析链路第一步Kakao Map 锚点解析当用户给出광화문这类文本地点时包执行以下链路见 resolveAnchor请求https://m.map.kakao.com/actions/searchView?qquery获取搜索页 HTML用 parseSearchResultsHtml 正则提取search_item base列表项得到候选的id、名称、类别、地址、电话用 rankAnchorCandidates 对候选打分排序名称完全匹配 1000、名称含역后缀变体 950、前缀匹配 800、包含匹配 600、地址包含 120并对역/광장/공원等锚点类别加分、对주차장类结果减分、对非纯数字 id 减分最终按分数降序、韩语 locale 排序依次请求https://place-api.map.kakao.com/places/panel3/confirmId获取场所面板 JSON用 normalizeAnchorPanel 归一化为带latitude/longitude的锚点若某个候选的面板请求返回 4xx/5xx 且属于可恢复错误则跳过继续尝试下一个见 isRecoverablePlacePanelError全部候选都拿不到可用坐标时抛出No usable Kakao Map place panel was available for query。测试 searchNearbyParkingLotsByLocationQuery resolves a Kakao anchor... 完整验证了这一链路前两次调用分别命中searchView?q광화문与places/panel3/1001并断言锚点地址为 서울특별시 종로구 세종대로 172。第二步地址提示与官方数据检索拿到锚点坐标后包用 extractAddressHint 从锚点地址中提取前两个词如 서울특별시 종로구作为addressHint再把它作为rdnmadr前缀传给官方 API从而把全韩数据快速收敛到目标市/区随后在客户端完成距离过滤与排序。标准化函数 normalizeParkingLotRows 做了以下关键工作兼容多种响应结构getParkingItems依次识别response.body.items、body.items、items及items.item数组/单对象等形态按坐标过滤用哈弗辛公式haversineDistanceMeters地球半径 6371008.8 米计算每个停车场与锚点的直线距离剔除超过radius默认 2000 米的记录字段双语归一官方响应同时存在英文/韩文两种字段如prkplceNm/주차장명、prkcmprt/주차구획수统一映射为英文语义字段去重与排序以id::name::address::lat::lng为键去重最终按距离升序、名称韩语排序输出。每个标准化后的条目包含约 30 个字段覆盖名称、地址、距离、容量capacity、等级grade、隔日限行alternateDayEnforcement、运营日operatingDays、工作日/周六/公休日开放时间weekday/saturday/holiday、费用信息feeInfo、basicTime、basicCharge、addUnitTime、addUnitCharge、dailyTicketCharge、monthlyTicketCharge、支付方式paymentMethods、无障碍车位hasAccessibleParking、管理机关与电话、数据基准日期referenceDate以及 Kakao 地图跳转链接mapUrl形如https://map.kakao.com/link/map/name,lat,lng。测试 normalizeParkingLotRows keeps public parking metadata... 对夹具数据parking-api-response.json验证了上述映射如 광화문광장 공영주차장 被识别为 공영/노상、容量 20、工作日 09:00-21:00、无无障碍车位并生成了正确的mapUrl可以包含 민영 的用例 验证了publicOnly: false时会把 세종로 민영주차장 一并返回。此外夹具中一条坐标字段为空的记录会被自动过滤见normalizeParkingLotRows中对toNumber结果非有限值的判空。输入校验与边界约束searchNearbyParkingLotsByCoordinates对入参有严格校验见 index.jslatitude/longitude必须是有限数值否则抛出latitude and longitude must be finite numberslimit默认 5合法范围 1 50radius兼容旧参数maxDistanceMeters默认 2000合法范围 1 50000publicOnly支持布尔值以及0/false/n/no/민영포함等字符串归一见 normalizeBoolean。测试 searchNearbyParkingLotsByCoordinates validates inputs 逐一断言了这些错误分支确保非法参数在发起外部请求前就被拦截。모두의주차장Modu Parking集成状态README 明确回应了 Issue #135 提出的是否接入 모두의주차장问题当前版本不抓取、不调用任何非官方的 모두의주차장接口只有在出现经过批准、稳定且法律上可用的 API 契约后才会考虑接入。这一点也在 instruction.md 中被重申属于产品边界声明避免 Agent 误以为可以绕过官方数据源。运行环境与安装前提包的运行约束记录在 package.json 中Node.js 18依赖全局fetch源码中request函数会校验fetchImpl/global.fetch是否为函数通过 npm 安装后在任意 Node 项目中require(parking-lot-search)即可本地开发可用npm testnode --test与npm run lintnode --check验证包的正确性测试全部基于本地夹具test/fixtures/下的anchor-search.html、anchor-panel.json、parking-api-response.json与注入的假fetchImpl不发起任何真实外部请求因此可离线、稳定地复现核心逻辑。总结parking-lot-search的工程价值在于把自然语言地点 → 坐标 → 官方停车场数据这一复杂链路封装为两个高层函数默认代理模式让无 Key 用户开箱即用直连模式满足有 Data.go.kr API Key 的合规调用需求同时通过严格的参数校验、双语字段归一、距离排序去重和完整测试保证了输出结果的确定性。如需深入源码建议从 src/index.js 的主流程入口与 src/parse.js 的解析/标准化函数入手结合 test/index.test.js 中的端到端用例理解完整调用链。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考