# Location

# openLocation

iOS requires Extension SDK or MapSDK dependency. If both Extension SDK and MapSDK are depended on, the openLocation provided by MapSDK takes precedence.

Android requires MapSDK dependency (Google solution is temporarily not supported)

openLocation(Object object)

Opens the built-in map to view a location.

Parameters

Object object

Property Type Default Required Description
latitude number Yes Latitude, range -90~90, negative values indicate south latitude. Uses gcj02 coordinate system
longitude number Yes Longitude, range -180~180, negative values indicate west longitude. Uses gcj02 coordinate system
scale number 16 No Zoom level, range 5~18
name string No Location name
address string No Detailed address description
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for API call completion (executed for both success and failure)

Sample Code

ft.getLocation({
 type: 'gcj02', //Returns coordinates that can be used with ft.openLocation
 success (res) {
   const latitude = res.latitude
   const longitude = res.longitude
   ft.openLocation({
     latitude,
     longitude,
     scale: 18
   })
 }
})

Note

  • API authorization failure (iOS):
  1. User denied authorization, returns error: unauthorized, user has not granted location permission
  2. Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from applying for location permission
  • API authorization failure (Android):
  1. User denied authorization, the map View will locate to the default position, subsequent manual search and location selection is allowed

# getLocation

Supported from Base Library 1.3.9, iOS version 2.1.23

iOS requires Extension SDK dependency

Android requires Extension SDK or MapSDK dependency. If both Extension SDK and MapSDK are depended on, the getLocation provided by MapSDK takes precedence.

If encountering slow positioning or unsatisfactory positioning success rate when using Extension SDK on Android, you can integrate MapSDK to utilize the positioning capabilities provided by third-party positioning SDKs (Amap, Baidu, Tencent, Google). Otherwise, it is recommended to use the getLocation provided by the Extension SDK.

getLocation(Object object)

Gets the current geographic location and other information. This API cannot be called after the user leaves the Mini-Program.

Parameters

Object object

Property Type Default Required Description
type string wgs84 No wgs84 returns GPS coordinates, gcj02 returns coordinates that can be used with ft.openLocation
isHighAccuracy boolean false No Enable high-accuracy positioning
(Supported from iOS SDK 2.38.1, Android SDK 2.35.1)
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for API call completion (executed for both success and failure)

Note

  • API authorization failure (iOS):
  1. User denied authorization, returns error: unauthorized, user has not granted location permission
  2. Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from applying for location permission
  • API authorization failure (Android):
  1. User denied authorization, returns error: unauthorized, user has not granted permission to obtain location information
  2. Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from actively initiating permission requests

# choosePoi

iOS requires Extension SDK dependency

Android requires MapSDK dependency (Google solution is temporarily not supported)

choosePoi(Object object)

Opens POI list to select a location, supporting mixed selection of fuzzy positioning (accurate to city level) and precise positioning.

Parameters

Object object

Property Type Default Required Description
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for API call completion (executed for both success and failure)

object.success Callback Function

Parameters

Object res

Property Type Description
type number Value is 0 when selecting not to show location, 1 when selecting city, 2 when selecting precise location
city string City name
name string Location name
address string Detailed address
latitude string Latitude, floating-point number, range -90~90, negative values indicate south latitude. Uses gcj02 coordinate system
longitude string Longitude, floating-point number, range -180~180, negative values indicate west longitude. Uses gcj02 coordinate system

Note

  • API authorization failure (iOS):
  1. User denied authorization, returns error: unauthorized, user has not granted location permission
  2. Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from applying for location permission
  • API authorization failure (Android):
  1. User denied authorization, the map View will locate to the default position, subsequent manual search and location selection is allowed

# chooseLocation

Supported from Base Library 1container.3.9, iOS version 2.1.23

iOS requires Extension SDK or MapSDK dependency. If both Extension SDK and MapSDK are depended on, the openLocation provided by MapSDK takes precedence.

Android requires MapSDK dependency (Google solution is temporarily not supported)

chooseLocation(Object object)

Opens the map to select a location.

Parameters

Object object

Property Type Default Required Description
latitude number No Target latitude
longitude number No Target longitude
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for API call completion (executed for both success and failure)

object.success Callback Function

Parameters

Object res

Property Type Description
name string Location name
address string Detailed address
latitude string Latitude, floating-point number, range -90~90, negative values indicate south latitude. Uses gcj02 coordinate system
longitude string Longitude, floating-point number, range -180~180, negative values indicate west longitude. Uses gcj02 coordinate system

Note

  • API authorization failure (iOS):
  1. User denied authorization, returns error: unauthorized, user has not granted location permission
  2. Host-App prohibits Mini-Program from actively applying for permissions, returns error: unauthorized disableauthorized, SDK is prohibited from applying for location permission
  • API authorization failure (Android):
  1. User denied authorization, the map View will locate to the default position, subsequent manual search and location selection is allowed

# stopLocationUpdate

Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1

stopLocationUpdate(Object object)

Stops listening for real-time location changes, stops receiving messages in both foreground and background.

Parameters

Object object

Property Type Default Required Description
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for API call completion (executed for both success and failure)

# startLocationUpdateBackground

Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1

startLocationUpdateBackground(Object object)

Enables receiving location messages when the Mini-Program enters both foreground and background.

Parameters

Object object

Property Type Default Required Description
type string gcj02 No wgs84 returns GPS coordinates, gcj02 returns coordinates that can be used with ft.openLocation
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for API call completion (executed for both success and failure)

# startLocationUpdate

Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1

startLocationUpdate(Object object)

Enables receiving location messages when the Mini-Program enters the foreground.

Parameters

Object object

Property Type Default Required Description
type string gcj02 No wgs84 returns GPS coordinates, gcj02 returns coordinates that can be used with ft.openLocation
success function No Callback function for successful API call
fail function No Callback function for failed API call
complete function No Callback function for API call completion (executed for both success and failure)

# onLocationChange

Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1

onLocationChange(Object object)

Listens for real-time geographic location change events.

Parameters

Object object

Property Type Default Required Description
latitude number Latitude, range -90~90, negative values indicate south latitude. Uses gcj02 coordinate system
longitude number Longitude, range -180~180, negative values indicate west longitude. Uses gcj02 coordinate system
speed number Speed, unit m/s
accuracy number Position accuracy
altitude number Altitude, unit m
verticalAccuracy number Vertical accuracy, unit m (Cannot be obtained on Android, returns 0)
horizontalAccuracy number Horizontal accuracy, unit m

# offLocationChange

Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1

offLocationChange(Object object)

Removes the listener function for real-time geographic location change events.

Parameters

Object object

Property Type Default Required Description
listener function The listener function passed to onLocationChange. If this parameter is not passed, all listener functions are removed.

# onLocationChangeError

Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1

onLocationChangeError(Object object)

Triggered when listening for continuous positioning API returns failure.

Parameters

Object object

Property Type Default Required Description
errCode number Error code

# offLocationChangeError

Supported from Base Library 3.0.18, iOS SDK 2.39.1, Android SDK 2.39.1

offLocationChangeError(Object object)

Removes the listener function triggered when the continuous positioning API returns failure.

Parameters

Object object

Property Type Default Required Description
listener function

# convertCoordinateFromMap

Supported from Base Library 3.0.19

This API is implemented via Registering Custom Mini-Program Synchronous APIs, the Base Library itself does not directly provide this API

convertCoordinateFromMap(Object object)

Converts the latitude and longitude returned by the SDK using this API.

Parameters

Object object

Property Type Default Required Description
latitude number Yes Target latitude
longitude number Yes Target longitude

Note

  1. This is a synchronous API. After the APP implements this API, the Base Library will automatically call this API to convert coordinates in related APIs and components.
  2. APIs converted by the Base Library: chooseLocation, choosePoi, MapContext related APIs.
  3. Map component related events and properties will also be converted, e.g., latitude and longitude carried in bindtap, bindmarkertap...

# convertCoordinateFromApplet

Supported from Base Library 3.0.19

This API is implemented via Registering Custom Mini-Program Synchronous APIs

convertCoordinateFromApplet(Object object)

Converts the latitude and longitude input by the user using this API.

Parameters

Object object

Property Type Default Required Description
latitude number Yes Target latitude
longitude number Yes Target longitude

Note

  1. This is a synchronous API. After the APP implements this API, the Base Library will automatically call this API to convert coordinates in related APIs and components.
  2. APIs converted by the Base Library: openLocation, MapContext related APIs.
  3. Map component related events and properties will also be converted, e.g., latitude, longitude, polyline and other properties...
© FinClip with ❤ , Since 2017