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

tencentmap-lbs-skill

General & other

View repository

Updated 10-15 17:26

About this skill

Tencent Maps Location Services Skill

Tencent Maps Location Services provides developers with complete map data services, including nearby search, place search, route planning, travel planning, and other features.

Requirements

tmap-lbs

If tmap-lbs is not installed the first time you use it, please install tmap-lbs first. If the user needs to update it, the same command is used.

npm install @tencent-map/lbs-skills -g

Prerequisite Check: API Key

Check Steps

  1. Check whether a formal Key already exists (via tmap-lbs config get-key check, environment variable TMAP_WEBSERVICE_KEY , or the user has already provided it in the conversation)

  1. Case A: A formal Key has been detected

    Silently record the Key,and continue directly with the user's original intent, without any prompt or interruption。

  2. Case B: No formal Key detected

⛔ Mandatory interception (highest priority)

When no formal Key is detected,before the user explicitly completes the selection, it is prohibited to perform any of the following operations:

  • Analyze the user's requirements
  • Read any files or documents
  • Plan the implementation approach
  • Write any code
  • Call any API

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 After registration, you can configure it in the following ways:

  • Command line:tmap-lbs config set-key <你的Key>
  • Environment variable:export TMAP_WEBSERVICE_KEY=<你的Key> Or tell me directly in the conversation and I will configure it.

Alternatively, you can choose to use the preset trial Key provided by the Tencent Location Services platform (no registration required, ready to use). Please note the limitations of the Tencent Location Services trial Key:

  • Access frequency limit: call frequency is restricted, and rate limiting is triggered after exceeding it
  • Data stability is average, and it is not recommended for production environments
  • Interfaces such as electric vehicle routes are unavailable

Please tell me your choice:

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

After receiving the user's explicit reply, continue according to the user's choice:

  • The user provides a formal Key → configure or record the Key via tmap-lbs config set-key <key> , switch to formal mode, and continue processing the request
  • The user chooses the trial Key → switch to trial mode and continue processing the request (see "Trial Mode Call Rules" below)

Trial Mode Call Rules

Judgment principle: Only interfaces that "do not require passing through the user's Key" can use trial mode. Interfaces that require passing through the user's Key cannot be supported in trial mode, and the user must be required to configure a formal Key before calling them.

In experience mode, replace the request parameters according to the following rules:

  • Domain: Replace https://apis.map.qq.com with https://h5gw.map.qq.com
  • Key parameter: Set key=none
  • apptag parameter: Look up the corresponding apptag value in the table below according to the API path, and fill it in

⚠️ Experience mode has CORS cross-origin restrictions

h5gw.map.qq.com does not allow direct browser-side fetch(including localhost development environments). Experience mode must be called using JSONP, append the output=jsonp&callback=函数名 parameter to the request, and initiate the request by dynamically inserting a <script> tag. Tencent Location Service WebService API natively supports JSONP callbacks.

// ✅ 体验模式：JSONP 方式（浏览器端可用）
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);
}

// 示例：体验模式地理编码
jsonpRequest('https://h5gw.map.qq.com/ws/geocoder/v1', {
  address: '北京西站',
  key: 'none',
  apptag: 'lbs_geocoder'
}, (res) => console.log(res));

❌ Using JSONP in formal Key mode is not recommended: JSONP will expose the Key in plaintext in frontend code, posing a risk of Key leakage. A formal Key should be forwarded through tmap-lbs CLI or aserver-side proxyto forward requests, avoiding direct calls on the browser side.

apptag reference table:

API path apptag Corresponding scenario
/ws/geocoder/v1 lbs_geocoder Scenarios 1 and 4 (geocoding)
/ws/place/v1/search lbsplace_search Scenarios 1 and 2 (POI search)
/ws/place/v1/explore lbsplace_explore Scenario 1 (nearby search)
/ws/direction/v1/driving lbsdirection_driving Scenario 3 (driving route)
/ws/direction/v1/walking lbsdirection_walking Scenario 3 (walking route)
/ws/direction/v1/bicycling lbsdirection_bicycling Scenario 3 (cycling route)
/ws/direction/v1/transit lbsdirection_transit Scenario 3 (transit route)

APIs unavailable in experience mode(these APIs require passing through the user's own Key, which experience mode cannot support):

  • /ws/direction/v1/ebicycling/(electric vehicle route)

When a user requests the above unavailable APIs in experience mode, reply with the following content and stop, waiting for the user to choose:

⚠️ The "electric vehicle route" feature you are currently requesting is unavailable in experience mode and requires a formal Key to be configured before it can be called. Please go to the official website to apply for a formal Key → https://lbs.qq.com/dev/console/key/manage After applying, tell me your Key and you can switch to formal mode to continue using it.

After each API call in experience mode returns a result, the following reminder must be appended at the end of the reply (it must be added every time and cannot be omitted):

📌 Friendly reminder: You are currently using the preset experience Key of Tencent Location Service. Data stability and call frequency are both limited. It is recommended to apply for a formal Tencent Location Service Key as soon as possible → https://lbs.qq.com/dev/console/key/manage

Scenario handling instructions in experience mode:

  • Scenario 5 (trajectory visualization): No API Key is required. In experience mode, use the tmap-lbs trail command normally; there is no need to make experience mode HTTP requests.

Features

  • Search
    • Supports keyword and POI search
    • Supports nearby search based on center point coordinates and radius
  • Planning
    • Travel itinerary planning
    • Route planning (walking, driving, cycling, transit)
  • Data visualization
    • Map data visualization
    • Trajectory data visualization display

Use this skill when the user wants to search for addresses, places, nearby information (such as food, hotels, attractions, etc.), or plan routes.

Trigger conditions

The user has expressed one of the following intentions:

  • Search for a certain type of place or a specific place (e.g., "Where is the Forbidden City", "Search for hotels", "Find gas stations")
  • Search the surroundings based on a certain location (e.g., "food around Olympic Park", "gas stations near Beijing West Railway Station")
  • Contains keywords such as "search", "find", "look up", "nearby", "surrounding", "route", "planning", etc.
  • Travel planning (e.g., "Help me plan a one-day trip in Beijing", "Hangzhou West Lake sightseeing route")
  • Route planning (e.g., "How to get from the Forbidden City to Nanluoguxiang", "Plan a cycling route")
  • Trajectory visualization (e.g., "Help me generate a trajectory map", "Upload trajectory data", "GPS trajectory display")

Scenario determination

After receiving a user request, first determine which scenario it belongs to:

  • Scenario 1: The user searches fora certain type of place around or near a certain location, and the input contains both elements: "location" and "search category or POI type" (e.g., "food around Xizhimen", "hotels near Beijing South Railway Station", "search for milk tea shops near Asia Financial Center")
  • Scenario 2: POI detailed search (using Web service API)
  • Scenario 3: Route planning
  • Scenario 4: Travel planning
  • Scenario 5: Trajectory visualization (the user has provided a trajectory data address and wants to generate a trajectory map)

Scenario 1: Location-based surrounding or nearby search

The user wants to search fora certain type of place around or near a certain location. You need to first obtain the latitude and longitude of that location through the geocoding API, and then assemble the search link with coordinates.

📖 After matching this scenario,you must first read references/scene1-nearby-search.md to obtain the detailed execution steps, API format, complete examples, and reply templates, and execute strictly according to the steps in the document.

Scenario 2: POI detailed search

Use Tencent Maps tmap-lbs for POI search, supporting keyword search, city restriction, nearby search, etc.

📖 For detailed format, parameter descriptions, and returned data format, please refer to references/scene2-poi-search.md

Scenario 3: Route planning

Use Tencent Maps tmap-lbs to plan routes. Supports multiple travel modes such as walking, driving, cycling (bicycle), electric bike, and public transit.

📖 For detailed format, API endpoints for each travel mode, parameter descriptions, and returned data format, please refer to references/scene3-route-planning.md

Scenario 4: Travel planning

The user wants to travel to a certain city and has provided multiple attractions they want to visit. You need to plan the best itinerary route, and optionally recommend restaurants, hotels, etc. You need to first obtain the latitude and longitude of each attraction through the geocoding API, and then assemble the travel planning link.

📖 After matching this scenario,you must first read references/scene4-travel-planner.md to obtain the detailed execution steps, API format, complete examples, and reply templates, and execute strictly according to the steps in the document.

Scenario 5: Map data visualization

When the user has a set of data containing trajectory coordinates and wants to visualize it on a map in the form of a trajectory map. No API Key is required.

Trigger conditions

The user mentions intentions such as "trajectory", "trajectory map", "trajectory visualization", "GPS trajectory", "movement trajectory", "driving trajectory", etc., and provides a data address or trajectory data.

📖 After matching this scenario,you must first read references/scene5-trail-map.md to obtain the detailed URL format, execution steps, complete examples, and reply templates, and execute strictly according to the steps in the documentation.

Notes

  • Scenario determination is key: distinguish whether the user is "directly searching for something", "searching for something near a certain location", "planning a route", or "travel planning"
  • Keywords should be as concise and accurate as possible, extracting what the user actually wants to search for
  • The browser will automatically handle the encoding of Chinese keywords in the URL, so there is no need to manually encode
  • The Tencent Maps coordinate format is 纬度,经度(note: latitude first, longitude second)
  • If the API returns status not equal to 0, it indicates that the request failed, and the user should be prompted to check whether the address is valid
  • Please keep the API Key secure and never share it with others

Documentation references (references)

The detailed operation documentation for each scenario is stored under the references/ directory:

File Description
references/scene1-nearby-search.md Scenario 1: Nearby search — execution steps, API format, complete examples, reply templates
references/scene2-poi-search.md Scenario 2: POI detailed search — request format, parameter descriptions, returned data format
references/scene3-route-planning.md Scenario 3: Route planning — request format, API endpoints, parameters, and returned data description
references/scene4-travel-planner.md Scenario 4: Travel planning — usage method, feature description
references/scene5-trail-map.md Scenario 5: Trajectory visualization — URL format, execution steps, complete examples, reply templates

Related links