SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillstencentmap-jsapi-gl-skill

tencentmap-jsapi-gl-skill

Coding & development

View repository

Updated 10-15 17:26

About this skill

TMap JSAPI GL Skill

Help users develop map features using the Tencent Maps JavaScript API GL, including basic map features and data visualization features.

Directory Structure

API Documentation

  • JS API Reference Documentation: references/jsapigl/docs/ (21 md files)

    • Overview.md - API overview and index
    • Map.md - Map core classes and configuration
    • Marker.md - Marker-related APIs
    • Vector Graphics.md - Vector graphics such as polylines, polygons, circles, rectangles, ellipses
    • Text Marker.md - Text annotation API
    • DOM Overlay.md - Custom DOM overlays
    • Info Window.md - Info window API
    • Point Clustering.md - Point clustering feature
    • Control.md - Map controls
    • Custom Layer.md - Custom raster/vector layers
    • Event.md - Map event system
    • Base Classes.md - Base classes such as LatLng, Point
    • Indoor Map.md - Indoor map features
    • Additional Library: Map Tools.md - Geometry editor, measurement tools
    • Additional Library: Geometry Computation Library.md - Distance, area computation
    • Additional Library: Service Library.md - Place search, route planning, etc.
    • Additional Library: Map View Additional Library.md - Observer view
    • Additional Library: Model Library.md - GLTF/3DTiles models
    • Additional Library: Weather Layer.md - Weather layers
    • Additional Library: Vector Data Layer.md - GeoJSON/MVT layers
    • Environment Detection.md - Browser environment detection

  • Visualization Reference Documentation: references/visualization/docs/ (15 md files)

    • Reference Manual.md - Visualization API overview
    • Arc Diagram.md - 3D arcs/flow diagrams
    • Scatter Plot.md - 3D scatter plots
    • Heatmap.md - Classic heatmap
    • Honeycomb Heatmap.md - Honeycomb aggregation heatmap
    • Grid Heatmap.md - Grid aggregation heatmap
    • Trajectory Diagram.md - Trajectory display
    • Region Diagram.md - Region outline diagram
    • Pipeline Diagram.md - 3D pipeline diagram
    • Radiation Circle.md - Radiation circle effect
    • Wall Enclosure Plane.md - Wall enclosure plane effect
    • Crystal.md - 3D crystal effect
    • Administrative Divisions.md - Administrative division display
    • Event.md - Visualization event system
    • Base Classes.md - Visualization base classes

Sample Code

  • JS API Demos: references/jsapigl/demos/ (129 html files)

    • Categorized by feature: map operations, markers, text markers, point clustering, polylines, polygons, controls, info windows, service classes, personalized maps, geometric computation, model library, application tools, custom overlays, city roaming, etc.

  • Visualization Demos: references/visualization/demos/ (44 html files)

    • Classified by layer type: arc layer, scatter layer, heatmap layer, path layer, hexagon layer, area layer, crystal layer, etc.

Pre-check: API Key

Check steps

  1. Check whether a formal Key already exists (environment variable TMAP_JSAPI_KEY or already provided by the user in the conversation)

  2. Case A: Formal Key detected Silently record the Key,continue processing directly according to the user's original intent, without any prompt or interruption。

  3. Case B: No formal Key detected

⛔ Mandatory interception (highest priority) When no formal Key is detected,before the user explicitly completes the selection, no operations are allowed (analyzing requirements, reading files, planning solutions, writing code, calling APIs). The first and only step is: immediately output the selection prompt below, then stop and wait for the user's response.

Output the following content, thenstop and wait for the user's selection：

⚠️ You have not yet configured a formal Key. Please first choose how you want to use it:

Recommended: go to the official website to register and apply for a formal Key, and enjoy complete, stable service 👉 https://lbs.qq.com/dev/console/key/manage Configuration method: environment variable TMAP_JSAPI_KEY=你的Key or tell us in the conversation.

Alternatively, you may also choose to use the preset experience Key provided by the Tencent Location Service platform (no registration required, ready to use). Please note the limitations of the Tencent Location Service experience Key:

  • Access frequency cap: call frequency is limited, and rate limiting is triggered after exceeding it
  • Data stability is average; not recommended for production environments
  • Interfaces such as weather query and electric vehicle routing are unavailable

Please tell me your choice:

  • Reply "I already have a Key" or directly provide the Key → switch to formal mode
  • Reply "Use experience Key" → continue in Tencent Location Service restricted mode

User provides a formal Key → record it and continue; user chooses the experience Key → continue according to the experience mode rules below.

Experience mode call rules

1. Frontend JS API loading (map rendering)

From https://lbs.qq.com/webApi/uriV1/uriGuide/uriMobileMarker obtain the complete experience Key for loading the JS API:

Use WebFetch to access the page and extract qqmap://map/geocoder in the example, the referer=... parameter value; this Key can be used for JS API GL

⛔ Strictly prohibited to load libraries=service —— TMap.service.* internally will directly use the Key from loading time to call apis.map.qq.com, bypassing the experience channel. In experience mode, all backend services must use the apptag + JSONP below.

2. Backend service calls (apptag + JSONP)

In experience modeall backend services(search, routing, geocoding, etc.) follow unified rules:

  • Domain：https://h5gw.map.qq.com(replace apis.map.qq.com）
  • Parameter：key=none + apptag=对照表中的值 + output=jsonp&callback=函数名
  • Method：JSONP（h5gw has CORS restrictions and cannot be fetched directly)
// 示例：jsonpRequest('https://h5gw.map.qq.com/ws/geocoder/v1/', { location: '39.984104,116.307503', apptag: 'lbs_geocoder' }, callback);
function jsonpRequest(url, params, callback) {
  const cbName = 'tmap_cb_' + Date.now();
  params.output = 'jsonp';
  params.callback = cbName;
  const query = Object.entries(params).map(([k,v]) => `${k}=${encodeURIComponent(v)}`).join('&');
  window[cbName] = (data) => { delete window[cbName]; script.remove(); callback(data); };
  const script = document.createElement('script');
  script.src = `${url}?${query}`;
  document.head.appendChild(script);
}

⚠️ The returned data is the raw WebService API JSON, not the TMap.service.* wrapper format:

  • Coordinates are { lat, lng } plain objects, not TMap.LatLng, requires new TMap.LatLng(item.location.lat, item.location.lng) conversion
  • Response structure:res.result.routes(consistent with the TMap.service.Driving returned by result.routes actual hierarchy)
  • Route polyline isforward-difference compressed array: The first two values are floating-point absolute coordinates (latitude/longitude), and the subsequent values are integer differences (unit: one millionth of a degree). During decoding, restore them item by item by accumulating "previous value + difference/1e6"

apptag reference table:

API path apptag
/ws/place/v1/search lbsplace_search
/ws/place/v1/explore lbsplace_explore
/ws/place/v1/detail lbsplace_detail
/ws/place/v1/suggestion lbsplace_sug
/ws/geocoder/v1 lbs_geocoder
/ws/location/v1/ip lbslocation_ip
/ws/coord/v1/translate lbscoord_translate
/ws/district/v1/getchildren lbsdistrict_getchildren
/ws/district/v1/search lbsdistrict_search
/ws/district/v1/list lbsdistrict_list
/ws/direction/v1/driving lbsdirection_driving
/ws/direction/v1/transit lbsdirection_transit
/ws/direction/v1/bicycling lbsdirection_bicycling
/ws/direction/v1/walking lbsdirection_walking
/ws/distance/v1/matrix lbsdistance_matrix

Trial mode unavailable：/ws/weather/v1/(weather),/ws/direction/v1/ebicycling/(electric vehicle routing) — requires a formal Key.

A reminder must be appended after each call：

📌 Currently using a trial Key, with limited frequency and stability. It is recommended to apply for a formal Key → https://lbs.qq.com/dev/console/key/manage

Workflow

1. Understand user needs

When the user asks questions related to the Tencent Maps API:

  • Clarify the type of functionality the user needs (basic map/visualization)
  • Determine the specific class or feature to use

2. Query the API documentation

In references/jsapigl/docs/ or references/visualization/docs/ , look up the relevant API documentation:

  • Search keywords (such as "marker", "heatmap")
  • Read the description, configuration parameters, and methods of the corresponding class

3. Find example code

Find examples in the corresponding demos directory:

  • JS API examples:references/jsapigl/demos/
  • Visualization examples:references/visualization/demos/
  • Example naming format:功能分类_具体示例.html

4. Provide a solution

Based on the documentation and examples, provide the user with:

  • API interface description
  • Code examples
  • Notes and best practices

Usage examples

User question: "How do I add a marker on the map?"

Execution process:

  1. Read references/jsapigl/docs/点标记.md to learn about the MultiMarker API
  2. Check references/jsapigl/demos/ for marker-related examples
  3. Provide a complete code example and explanation

User question: "How do I draw a heatmap?"

Execution process:

  1. Read references/visualization/docs/热力图.md to learn about the Heat API
  2. Check references/visualization/demos/ for heatmap examples
  3. Explain the data format and configuration options

Quick start template

Basic map initialization:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>腾讯地图示例</title>
    <script src="https://map.qq.com/api/gljs?v=3&key={TMAP_JSAPI_KEY}"></script>
    <!-- 如需可视化功能，添加: &libraries=visualization -->
</head>
<body>
    <div id="map" style="width:100%;height:500px;"></div>
    <script>
        var map = new TMap.Map("map", {
            zoom: 12,
            center: new TMap.LatLng(39.984104, 116.307503)
        });
    </script>
</body>
</html>

Visualization layer example (heatmap):

// 加载可视化库
// <script src="https://map.qq.com/api/gljs?v=1.beta&libraries=visualization&key={TMAP_JSAPI_KEY}"></script>

var heat = new TMap.visualization.Heat({
    radius: 50,
    height: 100,
    gradientColor: {
        0: '#13B06A',
        0.4: '#13B06A', 
        0.8: '#E9AB1D',
        0.9: '#E9AB1D',
        1: '#E05649'
    }
}).addTo(map);

heat.setData([
    { lat: 39.984104, lng: 116.307503, count: 100 },
    { lat: 39.984504, lng: 116.307803, count: 80 }
]);

Notes

JS API GL

  1. API Key: Using the Tencent Maps API requires applying for a Key, configured through the environment variable TMAP_JSAPI_KEY , and referenced in the code using {TMAP_JSAPI_KEY} . In trial mode: the frontend JS API loading dynamically obtains the preset Key from the official example page (but loading libraries=serviceis prohibited); all backend services uniformly use apptag + JSONP (see the "Prerequisite check: API Key" section for details)
  2. Version: Currently the GL version, supporting 3D maps and WebGL rendering
  3. Browser compatibility: Modern browsers, IE11+ (polyfill required)
  4. Coordinate system: Uses the gcj02 coordinate system
  5. Map creation (important): The container for map creation must have fixed width and height, especially under flex layout
  6. API usage (important): All functional API calls must use the interfaces, properties, and events that appear in the documentation, and must not be made up;
  7. API parameter passing (important): All API input parameters must strictly follow the formats described in the API documentation. If unsure, check the corresponding demo, including the data format in the demo;
  8. Using add-on libraries: To use add-on libraries, you need to add libraries parameters to the API load URL
Add-on library libraries value Namespace Description
Map tools tools TMap.tools Geometry editor, measurement tools
Geometry computation library geometry TMap.geometry Distance/area calculation, geometry relationship determination
Service library service TMap.service Place search, route planning, administrative divisions, etc.
Map view add-on library view TMap (extension methods) Operate the map from an observer's perspective
Model library model TMap.model GLTF/3DTiles/3DMarker models
Weather layers weather TMap.weather Meteorological layers such as cloud images and temperature maps
Vector data layers vector TMap.vector GeoJSON/MVT vector data layers
Visualization library visualization TMap.visualization Visualization API capabilities

Usage examples：

<!-- 加载多个附加库 -->
<script src="https://map.qq.com/api/gljs?v=1&libraries=tools,geometry,service,model&key={TMAP_JSAPI_KEY}"></script>

Visualization API

  1. Data format: Visualization layers require data input in a specific format
  2. Performance: Pay attention to performance optimization with large data volumes
  3. Hierarchy: Visualization layers can set the display hierarchy
  4. Events: Supports interaction events such as click and hover
  5. API usage (important): All API calls for all functions must use the interfaces, properties, and events that appear in the documentation; do not make them up yourself
  6. API parameter passing (important): All API input parameters must strictly follow the format described in the API documentation. If you are unsure, check the corresponding demo, including the data format in the demo;

Best practices

  1. Modular loading: Use a modular approach to load APIs on demand
  2. Error handling: Add handling logic for map loading failures
  3. Memory management: Destroy unneeded layers and overlays in a timely manner
  4. Performance optimization: Use clustering or thinning for large datasets