We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
Advanced filters
API versionAll
DeviceAll
Atomic service APIsNot filter by this
ReferencesApplication ServicesMap KitArkTS APIpetalMaps (Starting the Map App)

petalMaps (Starting the Map App)

Last updated: 2026-09-04 06:52
Content overview
Expand

This module provides the function of starting the map app.

Since: 5.0.3(15)

Modules to Import

Collapse
Word wrap
Dark theme
Copy code
  1. import { petalMaps } from '@kit.MapKit';

openMapHomePage

Phone5.0.3(15)+PC/2in16.0.0(20)+Tablet5.0.3(15)+

openMapHomePage(context: common.Context): Promise<void>

Opens the home screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Expand
Name Type Mandatory Description
context common.Context Yes Context.

Returns:

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Expand
ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. await petalMaps.openMapHomePage(this.getUIContext().getHostContext());

openMapPoiDetail

openMapPoiDetail(context: common.Context, poiDetailParams: PoiDetailParams): Promise<void>

Opens the POI details screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Expand
Name Type Mandatory Description
context common.Context Yes Context.
poiDetailParams PoiDetailParams Yes Parameters for POI details.

Returns:

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Expand
ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.PoiDetailParams = {
  2.   destinationPosition: {
  3.     latitude: 30.983015468224288,
  4.     longitude: 118.78058590757131
  5.   }
  6. };
  7. await petalMaps.openMapPoiDetail(this.getUIContext().getHostContext(), params);

openMapTextSearch

Phone5.0.3(15)+PC/2in16.0.0(20)+Tablet5.0.3(15)+

openMapTextSearch(context: common.Context, textSearchParams: TextSearchParams): Promise<void>

Opens the text search screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Expand
Name Type Mandatory Description
context common.Context Yes Context.
textSearchParams TextSearchParams Yes Parameters for text search.

Returns:

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Expand
ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.TextSearchParams = {
  2.   destinationName: 'Cloud Park'
  3. };
  4. await petalMaps.openMapTextSearch(this.getUIContext().getHostContext(), params);

openMapRoutePlan

openMapRoutePlan(context: common.Context, routePlanParams: RoutePlanParams): Promise<void>

Opens the route planning screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Expand
Name Type Mandatory Description
context common.Context Yes Context.
routePlanParams RoutePlanParams Yes Parameters for route planning.

Returns:

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Expand
ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.RoutePlanParams = {
  2.   destinationPosition: {
  3.     latitude: 31.983015468224288,
  4.     longitude: 118.78058590757131
  5.   }
  6. };
  7. await petalMaps.openMapRoutePlan(this.getUIContext().getHostContext(), params);

openMapNavi

openMapNavi(context: common.Context, naviParams: NaviParams): Promise<void>

Opens the navigation screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Parameters:

Expand
Name Type Mandatory Description
context common.Context Yes Context.
naviParams NaviParams Yes Parameters for navigation.

Returns:

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Expand
ID Error Message
401 Invalid input parameter.
1002600014 Failed to start the map app.
801

Capability not supported. Failed to call the API due to limited device capabilities.

Applicable versions: 5.1.0(18)+

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.NaviParams = {
  2.   destinationPosition: {
  3.     latitude: 31.983015468224288,
  4.     longitude: 118.78058590757131
  5.   }
  6. };
  7. await petalMaps.openMapNavi(this.getUIContext().getHostContext(), params);

openMapTaxi

Phone6.0.1(21)+Tablet6.0.1(21)+

openMapTaxi(context: common.Context, taxiParams: TaxiParams): Promise<void>

Opens the ride hailing screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 6.0.1(21) or later, this API is supported on phones and tablets. On other device types, it returns error code 801.

Since: 6.0.1(21)

Parameters:

Expand
Name Type Mandatory Description
context common.Context Yes Context.
taxiParams TaxiParams Yes Parameters for ride hailing.

Returns:

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Expand
ID Error Message
1002600014 Failed to start the map app.
801 Capability not supported. Failed to call the API due to limited device capabilities.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.TaxiParams = {
  2.   destinationPosition: {
  3.     latitude: 31.983015468224288,
  4.     longitude: 118.78058590757131
  5.   }
  6. };
  7. await petalMaps.openMapTaxi(this.getUIContext().getHostContext(), params);

openMapOfflineDataManagement

openMapOfflineDataManagement(context: common.Context, offlineDataParams: OfflineDataParams): Promise<void>

Opens the offline map management screen of the map app. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 6.1.1(24) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 6.1.1(24)

Parameters:

Expand
Name Type Mandatory Description
context common.Context Yes Context.
offlineDataParams OfflineDataParams Yes Parameters for offline map management.

Returns:

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Expand
ID Error Message
1002600014 Failed to start the map app.
801 Capability not supported. Failed to call the API due to limited device capabilities.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.OfflineDataParams = {
  2.   scenarios: 'PHONE'
  3. };
  4. await petalMaps.openMapOfflineDataManagement(this.getUIContext().getHostContext(), params);

PoiDetailParams

Defines parameters for POI details.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Expand
Name Type Read-Only Optional Description
destinationPosition mapCommon.LatLng No No

POI coordinates.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
destinationName string No Yes POI name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
destinationPoiId string No Yes

POI ID.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
zoom number No Yes

Zoom level of the map. The value ranges from 3 to 20. The default value is 17. If an invalid value is passed, the default value will be used.

Note:

When destinationPoiId is set, the map zoom level cannot be customized.

Since: 6.0.1(21)
coordinateType mapCommon.CoordinateType No Yes

Coordinate system of the map. The default value is mapCommon.CoordinateType.GCJ02. If an invalid value is passed, the default value will be used.

Since: 6.0.1(21)
destinationAddress string No Yes

POI description. For the default value and invalid values, the corresponding description will be obtained through reverse geocoding.

Since: 6.1.1(24)

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.PoiDetailParams = {
  2.   destinationPosition: {
  3.     latitude: 31.968789,
  4.     longitude: 118.798537
  5.   },
  6.   destinationName: 'Marker',
  7.   zoom: 17,
  8.   coordinateType: mapCommon.CoordinateType.GCJ02,
  9.   destinationAddress: 'This is the demo address.'
  10. };

TextSearchParams

Phone5.0.3(15)+PC/2in16.0.0(20)+Tablet5.0.3(15)+

Defines parameters for text search.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Expand
Name Type Read-Only Optional Description
destinationName string No Yes Destination name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.TextSearchParams = {
  2.   destinationName: 'Cloud Park'
  3. };

RoutePlanParams

Defines parameters for route planning.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Expand
Name Type Read-Only Optional Description
originPosition mapCommon.LatLng No Yes

Coordinates of the departure place. The default value is the user's current coordinates.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
originName string No Yes Departure place name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
originPoiId string No Yes

POI ID of the departure place.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
destinationPosition mapCommon.LatLng No No

Coordinates of the destination.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
destinationName string No Yes Destination name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
destinationPoiId string No Yes

POI ID of the destination.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
vehicleType VehicleType No Yes

Mode of transportation.

The default value is VehicleType.DRIVING. If an invalid value is passed, the default value will be used.
coordinateType mapCommon.CoordinateType No Yes

Coordinate system of the map. The default value is mapCommon.CoordinateType.GCJ02. If an invalid value is passed, the default value will be used.

Since: 6.0.1(21)

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.RoutePlanParams = {
  2.   destinationPosition: {
  3.     latitude: 31.983015468224288,
  4.     longitude: 118.78058590757131
  5.   }
  6. };
Phone5.0.3(15)+PC/2in16.0.0(20)+Tablet5.0.3(15)+

Defines parameters for navigation.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Expand
Name Type Read-Only Optional Description
destinationPosition mapCommon.LatLng No No

Coordinates of the destination.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
destinationName string No Yes Destination name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
destinationPoiId string No Yes

POI ID of the destination.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
vehicleType VehicleType No Yes

Mode of transportation.

The default value is VehicleType.DRIVING. If an invalid value is passed, the default value will be used.
originPosition mapCommon.LatLng No Yes

Coordinates of the departure place. The default value is the user's current coordinates.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.

Since: 6.0.1(21)
originName string No Yes

Departure place name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).

Since: 6.0.1(21)
originPoiId string No Yes

POI ID of the departure place.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.

Since: 6.0.1(21)
coordinateType mapCommon.CoordinateType No Yes

Coordinate system of the map. The default value is mapCommon.CoordinateType.GCJ02. If an invalid value is passed, the default value will be used.

Since: 6.0.1(21)

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.NaviParams = {
  2.   destinationPosition: {
  3.     latitude: 31.983015468224288,
  4.     longitude: 118.78058590757131
  5.   }
  6. };

OfflineDataParams

Describes parameters for offline map management.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 6.1.1(24) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 6.1.1(24)

Expand
Name Type Read-Only Optional Description
scenarios string No No

Scenario description.

Note:

Currently, only WATCH, PHONE, TABLET, PC, and VOICE are supported, and the values are case-insensitive.

WATCH: opens the offline map management screen on the watch for offline map management.

PHONE: opens the map resource management screen for local offline map management.

TABLET: opens the map resource management screen for local offline map management.

PC: opens the map resource management screen for local offline map management.

VOICE: opens the navigation voice screen for local offline navigation voice management.
recommendedRegionIds string[] No Yes Set of recommended regions for offline map download. The maximum length is 20. If an invalid value is passed, error code 401 is returned.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.OfflineDataParams = {
  2.   scenarios: 'PHONE'
  3. };

VehicleType

Mode of transportation. Currently, the map app supports only driving, walking, cycling, and public transit.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 5.1.1(19) or earlier, this API is supported on phones and tablets. On other device types, it returns error code 801. For version 6.0.0(20) or later, this API is supported on phones, tablets, and PCs/2-in-1 devices. On other device types, it returns error code 801.

Since: 5.0.3(15)

Expand
Name Value Description
DRIVING 0 Driving.
WALKING 1 Walking.
CYCLING 2 Cycling.
TRANSIT 3

Public transit.

Since: 6.0.1(21)

TaxiParams

Defines parameters for ride hailing.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Map.Core

Device behavior differences: For version 6.0.1(21) or later, this API is supported on phones and tablets. On other device types, it returns error code 801.

Since: 6.0.1(21)

Expand
Name Type Read-Only Optional Description
destinationPosition mapCommon.LatLng No No

Coordinates of the destination.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
destinationName string No Yes Destination name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
destinationPoiId string No Yes

POI ID of the destination.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
originPosition mapCommon.LatLng No Yes

Coordinates of the departure place. The default value is the user's current coordinates.

The value ranges from -180 to 180 (excluded) for the longitude and from -85.2 to 85.2 for the latitude. Error code 401 will be returned for any invalid value.
originName string No Yes Departure place name. If the name exceeds the display limit, the overflowing part will be replaced with an ellipsis (...).
originPoiId string No Yes

POI ID of the departure place.

When both the POI ID and coordinates are passed in, the POI ID will be used preferentially.
coordinateType mapCommon.CoordinateType No Yes Coordinate system of the map. The default value is mapCommon.CoordinateType.GCJ02. If an invalid value is passed, the default value will be used.

Example:

Collapse
Word wrap
Dark theme
Copy code
  1. let params: petalMaps.TaxiParams = {
  2.   destinationPosition: {
  3.     latitude: 31.983015468224288,
  4.     longitude: 118.78058590757131
  5.   }
  6. };
navi (Route Planning)
sceneMap (Scenario-specific Control)
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in References
Enter a keyword.