Tencent Maps

Platforms and setup

Native platforms: ios, android.

• Every action except open requires a nonempty provider developer key in referer.
• view accepts title and address together or neither.
• No Android store action is configured; the provider download page is the generic website fallback.
• Native requests do not receive web-only coord_type. CurrentLocation nearby fallback is mobile-only.
• Web route endpoint supports driving/transit/walking; bicycling fallback uses the destination geocoder.

Public actions

• TencentMaps.open
• TencentMaps.view
• TencentMaps.search
• TencentMaps.nearbySearch
• TencentMaps.directionsWithCoords

factory TencentMaps.open({final bool fallbackToStore = false})

static TencentMapsViewAction view({ required final Coordinate coordinate, required final String referer, final String? title, final String? address, final TencentMapsCoordType coordType = TencentMapsCoordType.tencent, final bool fallbackToStore = false, })

static TencentMapsSearchAction search({ required final String query, required final String referer, final String? region, final bool fallbackToStore = false, })

static TencentMapsNearbySearchAction nearbySearch({ required final String query, required final String referer, final Coordinate? center, final int radius = 1000, final TencentMapsCoordType coordType = TencentMapsCoordType.tencent, final bool fallbackToStore = false, })

static TencentMapsDirectionsWithCoordsAction directionsWithCoords({ required final Coordinate destination, required final String referer, final Coordinate? origin, final String? destinationTitle, final String? originTitle, final String? destinationPoiId, final List<TencentMapsWaypoint> waypoints = const [], final TencentMapsTravelMode mode = TencentMapsTravelMode.driving, final TencentMapsCoordType coordType = TencentMapsCoordType.tencent, final bool fallbackToStore = false, })

Provider setup and examples

DeeplinkX supports Tencent Maps on iOS and Android for opening the app, displaying a coordinate or marker, searching, nearby searching, and coordinate route planning.

References

• Mobile URI guide
• Mobile marker and geocoder
• Mobile search
• Mobile route planning
• Web marker and geocoder
• Web search
• Web route planning
• Official Android distribution page

Developer Key

Tencent's mobile URI contract requires a developer key in the referer parameter. Create a key in the Tencent Location Service console, then pass it to every action except open.

const tencentMapsKey = 'YOUR_TENCENT_MAPS_KEY';

DeeplinkX rejects an empty key. It does not include or log a key for you.

Available Actions

Open App

final deeplinkX = DeeplinkX();

await deeplinkX.launchApp(
  TencentMaps.open(fallbackToStore: true),
);

Tencent Maps currently has an iOS App Store action. Its old Google Play listing is not used. When a native launch has no matching store action, open uses Tencent's official cross-platform download page:

https://pr.map.qq.com/j/tmap/download

View Map

Pass only a coordinate to let Tencent Maps reverse-geocode it:

await deeplinkX.launchAction(
  TencentMaps.view(
    coordinate: const Coordinate(
      latitude: 39.867192,
      longitude: 116.493187,
    ),
    referer: tencentMapsKey,
  ),
);

Pass both title and address to display a custom marker:

await deeplinkX.launchAction(
  TencentMaps.view(
    coordinate: const Coordinate(
      latitude: 39.867192,
      longitude: 116.493187,
    ),
    title: 'Tencent Office',
    address: 'Beijing',
    coordType: TencentMapsCoordType.gps,
    referer: tencentMapsKey,
  ),
);

Supplying only one marker field throws ArgumentError.

Search

await deeplinkX.launchAction(
  TencentMaps.search(
    query: 'coffee',
    region: 'Shanghai',
    referer: tencentMapsKey,
  ),
);

Nearby Search

await deeplinkX.launchAction(
  TencentMaps.nearbySearch(
    query: 'restaurant',
    center: const Coordinate(
      latitude: 39.994745,
      longitude: 116.247282,
    ),
    radius: 800,
    coordType: TencentMapsCoordType.gps,
    referer: tencentMapsKey,
  ),
);

When center is omitted, native Tencent Maps and mobile web use CurrentLocation. Tencent documents that value as mobile-only, so a desktop browser may not complete a current-location nearby search.

Directions With Coordinates

await deeplinkX.launchAction(
  TencentMaps.directionsWithCoords(
    origin: const Coordinate(
      latitude: 39.994745,
      longitude: 116.247282,
    ),
    originTitle: 'Tsinghua',
    destination: const Coordinate(
      latitude: 39.867192,
      longitude: 116.493187,
    ),
    destinationTitle: 'Community',
    destinationPoiId: '12609347545913930473',
    waypoints: const [
      TencentMapsWaypoint(
        title: 'Metro Station',
        coordinate: Coordinate(
          latitude: 30.248015,
          longitude: 120.207788,
        ),
      ),
    ],
    mode: TencentMapsTravelMode.driving,
    coordType: TencentMapsCoordType.gps,
    referer: tencentMapsKey,
  ),
);

Tencent Maps supports driving, transit, walking, and bicycling in its Android and iOS URI. Up to 15 waypoints are accepted. When origin is omitted, the native URI uses CurrentLocation.

Tencent's web route endpoint supports driving, transit, and walking. The bicycling fallback therefore opens the destination through Tencent's web geocoder instead of inventing an unsupported cycling route.

Native And Web Parameter Differences

DeeplinkX builds native and web parameters separately:

• Native marker, geocoder, nearby-search, and route URIs do not receive the web-only coord_type parameter.
• coordType controls coordinate conversion in Tencent's HTTPS fallback. Native URIs receive the supplied coordinates unchanged.
• Native route destinationPoiId and waypoints are omitted from the web route because Tencent does not document touid or passes for that endpoint.
• A web route always receives a destination name. DeeplinkX uses Destination when destinationTitle is omitted.
• A destination-only web route omits origin parameters so mobile Tencent Maps can use the current location.

Platform Configuration

iOS

Add qqmap under LSApplicationQueriesSchemes:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>qqmap</string>
</array>

Android

Add the package and scheme intent under the manifest-level queries element:

<queries>
    <package android:name="com.tencent.map" />
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="qqmap" />
    </intent>
</queries>

URI Formats

• Open/download fallback: https://pr.map.qq.com/j/tmap/download
• Native marker: qqmap://map/marker?marker=...&referer={developerKey}
• Native coordinate geocoder: qqmap://map/geocoder?coord={latitude},{longitude}&referer={developerKey}
• Native search: qqmap://map/search?keyword={query}&region={region}&referer={developerKey}
• Native nearby search: qqmap://map/search?keyword={query}&center={coordinate|CurrentLocation}&radius={meters}&referer={developerKey}
• Native route: qqmap://map/routeplan?type={drive|bus|walk|bike}&fromcoord={origin|CurrentLocation}&tocoord={destination}&referer={developerKey}
• Web actions: matching https://apis.map.qq.com/uri/v1/... endpoints, with the documented web parameter set

Fallback Behavior

Set disableFallback: true on launchApp or launchAction to skip store and web fallbacks.