feat(tencent-map): add Tencent Maps geocoding adapter - #2525
Open
Ingress007 wants to merge 1 commit into
Open
Ingress007 wants to merge 1 commit into
Ingress007 wants to merge 1 commit into
Conversation
Add a tencent-map site adapter (腾讯位置服务) covering the four coordinate workflows the getPoint picker exposes, plus the one it does not: - search keyword -> candidate places with coordinates - address full address -> coordinate, with --verify reverse-checking it - locate coordinate -> address / admin divisions / nearest POI - convert WGS-84 / GCJ-02 / BD-09 conversion, computed locally Strategy is PUBLIC. The getPoint page is a thin front-end over h5gw.map.qq.com and those endpoints replay from Node with no cookie, no login and no browser. Two contract details are encoded because they are easy to get wrong: every request needs an apptag, and region(全国,0) is syntactically valid but always returns 0 rows, so a nationwide keyword lookup routes through place/v1/suggestion instead. convert is local math (no request, no quota). Its WGS-84 -> GCJ-02 output matches Tencent's own ws/coord/v1/translate?type=1 to six decimals, which the test suite asserts. It also reports shift_meters and inside_china so a no-op conversion outside mainland China is visible rather than implied. Matching is fuzzy even on success, so rows carry the API's own similarity / reliability / deviation fields rather than a hand-rolled verdict, and --verify reports what the resulting coordinate actually resolves to. Docs: new page, docs/adapters/index.md row, VitePress sidebar entry. Checks: opencli validate 0 errors / 0 warnings, convention-audit 0 violations, check:silent-column-drop and check:typed-error-lint show no new entries, 30 adapter tests pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a
tencent-mapadapter (腾讯位置服务) built on the WebService behind the coordinate picker. It is the registry's first geocoding / coordinate adapter — nothing currently toucheslbs.qq.com,apis.map.qq.comorh5gw.map.qq.com.search <keyword> [--region] [--limit]address <address> [--region] [--verify]locate <lat,lng>convert <coords> [--from] [--to]Related issue: none — no upstream issue mentions this site (searched for 腾讯地图 / tencent map / lbs.qq.com).
Type of Change
Contract and strategy
PUBLICwithbrowser: false. The getPoint page is a thin front-end overh5gw.map.qq.com, and those requests replay from Node with no cookie, no login and no browser — no Chrome session or Browser Bridge is involved.apptag, andplace/v1/searchrequires a realboundarywhileregion(全国,0)is syntactically valid but always returns zero rows. A nationwide keyword lookup therefore routes throughplace/v1/suggestion, and thesourcecolumn records which endpoint answered.convertis local math — no request, no quota, and it keeps working when the service is unreachable. Its WGS-84 → GCJ-02 output matches Tencent's ownws/coord/v1/translate?type=1to six decimals (asserted in the tests). Rows also carryshift_metersandinside_china, so the identity conversion outside mainland China is reported rather than implied.key=[你的key]placeholder that the gateway substitutes). Nothing is bypassed — no login, captcha or rate-limit workaround. The doc page notes the quota belongs to the site.Failure modes pinned down
天安门→348 参数错误, while北京市天安门resolves. That is anArgumentErrorwith a hint pointing at--regionorsearch, not an empty result.status 0withsimilarity 0.99anddeviation 1000. The tell is thattitle/levelcollapse from the POI (腾讯滨海大厦, level 10) to the street (海天二路, level 7). Rows carry the API's ownsimilarity/reliability/level/deviationinstead of a hand-rolled verdict, and--verifyreports what the resulting coordinate actually resolves back to.lat,lngis Tencent's own order (latitude first). A swapped pair is rejected with the corrected value in the hint rather than silently reinterpreted.--regionis folded into the query text because the gateway has no region parameter; the text actually sent is echoed in thequerycolumn.Verification
opencli validate tencent-map: 4 commands, 0 errors, 0 warnings.opencli convention-audit tencent-map: 0 violations across all seven rules.npx tsc --noEmit: pass.npm run build: pass — 1,370 manifest entries, and the committedcli-manifest.jsonis byte-identical to a fresh build.check:silent-column-drop/check:typed-error-lint: no new violations.npm run docs:build: pass.git show --check: pass.Screenshots / Output
Live replay also passed for nationwide keyword search, region-supplemented addresses, forward geocoding with and without
--verify, and batched conversions in all three systems (Shenzhen / Beijing / Hangzhou samples).Checklist
Documentation (if adding/modifying an adapter)
docs/adapters/(if new adapter)docs/adapters/index.mdtable (if new adapter)docs/.vitepress/config.mts(if new adapter)README.md/README.zh-CN.mdwhen command discoverability changed — the "Built-in Commands" table is a curated ~20-site highlight list that omits comparablePUBLICadapters (wttr, rest-countries, openfda), so no row was added. Happy to add one if that is preferred.CliErrorsubclasses instead of rawError