Skip to content

feat(tencent-map): add Tencent Maps geocoding adapter - #2525

Open
Ingress007 wants to merge 1 commit into
jackwener:mainfrom
Ingress007:feat/tencent-map-adapter
Open

Ingress007 wants to merge 1 commit into
jackwener:mainfrom
Ingress007:feat/tencent-map-adapter

Conversation

@Ingress007

Copy link
Copy Markdown

Description

Adds a tencent-map adapter (腾讯位置服务) built on the WebService behind the coordinate picker. It is the registry's first geocoding / coordinate adapter — nothing currently touches lbs.qq.com, apis.map.qq.com or h5gw.map.qq.com.

Command Purpose
search <keyword> [--region] [--limit] Keyword → candidate places with coordinates, address, POI id and phone
address <address> [--region] [--verify] Forward geocoding: full address → one coordinate, optionally reverse-checked
locate <lat,lng> Reverse geocoding: coordinate → address, administrative divisions and nearest POI
convert <coords> [--from] [--to] WGS-84 / GCJ-02 / BD-09 conversion, computed locally

Related issue: none — no upstream issue mentions this site (searched for 腾讯地图 / tencent map / lbs.qq.com).

Type of Change

  • 🌐 New site adapter

Contract and strategy

  • Strategy is PUBLIC with browser: false. The getPoint page is a thin front-end over h5gw.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.
  • Two gateway details are easy to get wrong, so the adapter encodes them: every request must carry an apptag, and place/v1/search requires a real boundary while region(全国,0) is syntactically valid but always returns zero rows. A nationwide keyword lookup therefore routes through place/v1/suggestion, and the source column records which endpoint answered.
  • convert is local math — no request, no quota, and it keeps working when the service is unreachable. Its WGS-84 → GCJ-02 output matches Tencent's own ws/coord/v1/translate?type=1 to six decimals (asserted in the tests). Rows also carry shift_meters and inside_china, so the identity conversion outside mainland China is reported rather than implied.
  • Requests reuse the credential the page itself sends (the literal 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

  • An address with no city component is rejected by the geocoder: 天安门348 参数错误, while 北京市天安门 resolves. That is an ArgumentError with a hint pointing at --region or search, not an empty result.
  • Matching is fuzzy even on success: a house number that does not exist still answers status 0 with similarity 0.99 and deviation 1000. The tell is that title / level collapse from the POI (腾讯滨海大厦, level 10) to the street (海天二路, level 7). Rows carry the API's own similarity / reliability / level / deviation instead of a hand-rolled verdict, and --verify reports what the resulting coordinate actually resolves back to.
  • lat,lng is Tencent's own order (latitude first). A swapped pair is rejected with the corrected value in the hint rather than silently reinterpreted.
  • --region is folded into the query text because the gateway has no region parameter; the text actually sent is echoed in the query column.

Verification

  • Focused adapter tests: 30/30 pass (mocked gateway payloads plus the coordinate math, CRS aliases, parsing guards and every typed-error path).
  • 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 committed cli-manifest.json is byte-identical to a fresh build.
  • check:silent-column-drop / check:typed-error-lint: no new violations.
  • Strict adapter documentation coverage: 180/180. npm run docs:build: pass. git show --check: pass.

Screenshots / Output

$ opencli tencent-map convert "22.523055,113.935258" -f json
[
  {
    "input": "22.523055,113.935258",
    "from": "wgs84",
    "to": "gcj02",
    "lat": 22.520025,
    "lng": 113.940125,
    "shift_meters": 602.82,
    "inside_china": true
  }
]

$ opencli tencent-map search "腾讯滨海大厦" --region 深圳市 --limit 1 -f json
[
  {
    "rank": 1,
    "title": "腾讯滨海大厦",
    "address": "广东省深圳市南山区海天二路33号",
    "lat": 22.522807,
    "lng": 113.935338,
    "category": "房产小区:商务楼宇",
    "tel": null,
    "poi_id": "10015633769202902297",
    "adcode": "440305",
    "province": "广东省",
    "city": "深圳市",
    "district": "南山区",
    "source": "search"
  }
]

$ opencli tencent-map locate "22.522807,113.935338" -f json
[
  {
    "lat": 22.522807,
    "lng": 113.935338,
    "address": "广东省深圳市南山区海天二路",
    "standard_address": "广东省深圳市南山区海天二路33号",
    "recommend_address": "南山区腾讯滨海大厦(海天二路西)",
    "nation": "中国",
    "province": "广东省",
    "city": "深圳市",
    "district": "南山区",
    "street": "海天二路",
    "street_number": null,
    "adcode": "440305",
    "phone_area_code": "0755",
    "nearest_poi": "腾讯滨海大厦",
    "poi_count": 10
  }
]

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

  • I ran the checks relevant to this PR
  • I updated tests or docs if needed
  • I included output or screenshots when useful

Documentation (if adding/modifying an adapter)

  • Added doc page under docs/adapters/ (if new adapter)
  • Updated docs/adapters/index.md table (if new adapter)
  • Updated sidebar in docs/.vitepress/config.mts (if new adapter)
  • Updated README.md / README.zh-CN.md when command discoverability changed — the "Built-in Commands" table is a curated ~20-site highlight list that omits comparable PUBLIC adapters (wttr, rest-countries, openfda), so no row was added. Happy to add one if that is preferred.
  • Used positional args for the command's primary subject unless a named flag is clearly better
  • Normalized expected adapter failures to CliError subclasses instead of raw Error

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant