• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Geographic Location
2
3> **NOTE**
4> - The APIs of this module are no longer maintained since API version 7. It is recommended that you use [`@ohos.geolocation`](js-apis-geolocation.md) instead.
5>
6> - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
7
8
9## Modules to Import
10
11
12```
13import geolocation from '@system.geolocation';
14```
15
16
17## Required Permissions
18
19ohos.permission.LOCATION
20
21
22## geolocation.getLocation
23
24getLocation(Object): void
25
26Obtains the geographic location.
27
28**System capability**: SystemCapability.Location.Location.Lite
29
30**Parameters**
31
32| Parameter | Type | Mandatory | Description |
33| -------- | -------- | -------- | -------- |
34| timeout | number | No | Timeout&nbsp;duration,&nbsp;in&nbsp;milliseconds.&nbsp;The&nbsp;default&nbsp;value&nbsp;is&nbsp;**30000**.<br/>The&nbsp;timeout&nbsp;duration&nbsp;is&nbsp;necessary&nbsp;in&nbsp;case&nbsp;the&nbsp;request&nbsp;to&nbsp;obtain&nbsp;the&nbsp;geographic&nbsp;location&nbsp;is&nbsp;rejected&nbsp;for&nbsp;the&nbsp;lack&nbsp;of&nbsp;the&nbsp;required&nbsp;permission,&nbsp;weak&nbsp;positioning&nbsp;signal,&nbsp;or&nbsp;incorrect&nbsp;location&nbsp;settings.&nbsp;After&nbsp;the&nbsp;timeout&nbsp;duration&nbsp;expires,&nbsp;the&nbsp;fail&nbsp;function&nbsp;will&nbsp;be&nbsp;called.<br/>The&nbsp;value&nbsp;is&nbsp;a&nbsp;32-digit&nbsp;positive&nbsp;integer.&nbsp;If&nbsp;the&nbsp;value&nbsp;set&nbsp;is&nbsp;less&nbsp;than&nbsp;or&nbsp;equal&nbsp;to&nbsp;**0**,&nbsp;the&nbsp;default&nbsp;value&nbsp;will&nbsp;be&nbsp;used. |
35| coordType | string | No | Coordinate&nbsp;system&nbsp;type.&nbsp;Available&nbsp;types&nbsp;can&nbsp;be&nbsp;obtained&nbsp;by&nbsp;**getSupportedCoordTypes**.&nbsp;The&nbsp;default&nbsp;type&nbsp;is&nbsp;**wgs84**. |
36| success | Function | No | Called&nbsp;when&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful. |
37| fail | Function | No | Called&nbsp;when&nbsp;the&nbsp;operation&nbsp;fails. |
38| complete | Function | No | Called&nbsp;when&nbsp;the&nbsp;execution&nbsp;is&nbsp;complete |
39
40The following values will be returned when the operation is successful.
41
42| Parameter | Type | Description |
43| -------- | -------- | -------- |
44| longitude | number | Longitude |
45| latitude | number | Latitude |
46| altitude | number | Altitude |
47| accuracy | number | Location&nbsp;accuracy |
48| time | number | Time&nbsp;when&nbsp;the&nbsp;location&nbsp;is&nbsp;obtained |
49
50One of the following error codes will be returned if the operation fails.
51
52| Error&nbsp;Code | Description |
53| -------- | -------- |
54| 601 | Failed&nbsp;to&nbsp;obtain&nbsp;the&nbsp;required&nbsp;permission&nbsp;because&nbsp;the&nbsp;user&nbsp;rejected&nbsp;the&nbsp;request. |
55| 602 | Permission&nbsp;not&nbsp;declared. |
56| 800 | Operation&nbsp;times&nbsp;out&nbsp;due&nbsp;to&nbsp;a&nbsp;poor&nbsp;network&nbsp;condition&nbsp;or&nbsp;unavailable&nbsp;GPS. |
57| 801 | System&nbsp;location&nbsp;disabled. |
58| 802 | The&nbsp;method&nbsp;is&nbsp;called&nbsp;again&nbsp;while&nbsp;the&nbsp;previous&nbsp;execution&nbsp;result&nbsp;is&nbsp;not&nbsp;returned&nbsp;yet. |
59
60**Example**
61
62```
63export default {
64  getLocation() {
65    geolocation.getLocation({
66      success: function(data) {
67        console.log('success get location data. latitude:' + data.latitude);
68      },
69      fail: function(data, code) {
70        console.log('fail to get location. code:' + code + ', data:' + data);
71      },
72    });
73  },
74}
75```
76
77
78## geolocation.getLocationType
79
80getLocationType(Object): void
81
82Obtains the supported location types.
83
84**System capability**: SystemCapability.Location.Location.Lite
85
86**Parameters**
87
88| Parameter | Type | Mandatory | Description |
89| -------- | -------- | -------- | -------- |
90| success | Function | No | Called&nbsp;when&nbsp;the&nbsp;execution&nbsp;is&nbsp;successful. |
91| fail | Function | No | Called&nbsp;when&nbsp;the&nbsp;operation&nbsp;fails. |
92| complete | Function | No | Called&nbsp;when&nbsp;the&nbsp;execution&nbsp;is&nbsp;complete |
93
94The following values will be returned when the operation is successful.
95
96| Parameter | Type | Description |
97| -------- | -------- | -------- |
98| types | Array&lt;string&gt; | Available&nbsp;location&nbsp;types,&nbsp;['gps',&nbsp;'network'] |
99
100**Example**
101
102```
103export default {
104  getLocationType() {
105    geolocation.getLocationType({
106      success: function(data) {
107        console.log('success get location type:' + data.types[0]);
108      },
109      fail: function(data, code) {
110        console.log('fail to get location. code:' + code + ', data:' + data);
111       },
112     });
113  },
114}
115```
116
117
118## geolocation.subscribe
119
120subscribe(Object): void
121
122Listens to the geographical location. If this method is called multiple times, the last call takes effect.
123
124**System capability**: SystemCapability.Location.Location.Lite
125
126**Parameters**
127
128| Parameter | Type | Mandatory | Description |
129| -------- | -------- | -------- | -------- |
130| coordType | string | No | Coordinate&nbsp;system&nbsp;type.&nbsp;Available&nbsp;types&nbsp;can&nbsp;be&nbsp;obtained&nbsp;by&nbsp;**getSupportedCoordTypes**.&nbsp;The&nbsp;default&nbsp;type&nbsp;is&nbsp;**wgs84**. |
131| success | Function | Yes | Called&nbsp;when&nbsp;the&nbsp;geographical&nbsp;location&nbsp;changes |
132| fail | Function | No | Called&nbsp;when&nbsp;the&nbsp;listening&nbsp;fails |
133
134The following values will be returned when the network type is obtained.
135
136| Parameter | Type | Description |
137| -------- | -------- | -------- |
138| longitude | number | Longitude |
139| latitude | number | Latitude |
140| altitude | number | Altitude |
141| accuracy | number | Location&nbsp;accuracy |
142| time | number | Time&nbsp;when&nbsp;the&nbsp;location&nbsp;is&nbsp;obtained |
143
144One of the following error codes will be returned if the operation fails.
145
146| Error&nbsp;Code | Description |
147| -------- | -------- |
148| 601 | Failed&nbsp;to&nbsp;obtain&nbsp;the&nbsp;required&nbsp;permission&nbsp;because&nbsp;the&nbsp;user&nbsp;rejected&nbsp;the&nbsp;request. |
149| 602 | Permission&nbsp;not&nbsp;declared. |
150| 801 | System&nbsp;location&nbsp;disabled. |
151
152**Example**
153
154```
155export default {
156  subscribe() {
157    geolocation.subscribe({
158      success: function(data) {
159        console.log('get location. latitude:' + data.latitude);
160      },
161      fail: function(data, code) {
162        console.log('fail to get location. code:' + code + ', data:' + data);
163      },
164    });
165  },
166}
167```
168
169
170## geolocation.unsubscribe
171
172unsubscribe(): void
173
174Cancels listening to the geographical location.
175
176**System capability**: SystemCapability.Location.Location.Lite
177
178**Example**
179
180```
181export default {
182  unsubscribe() {
183    geolocation.unsubscribe();
184  },
185}
186```
187
188
189## geolocation.getSupportedCoordTypes
190
191getSupportedCoordTypes(): Array&lt;string&gt;
192
193Obtains coordinate system types supported by the device.
194
195**System capability**: SystemCapability.Location.Location.Lite
196
197**Return Value**
198
199| Type | Non-Null | Description |
200| -------- | -------- | -------- |
201| Array&lt;string&gt; | Yes | Coordinate&nbsp;system&nbsp;types,&nbsp;for&nbsp;example,&nbsp;**[wgs84,&nbsp;gcj02]**. |
202
203**Example**
204
205```
206export default {
207  getSupportedCoordTypes() {
208    var types = geolocation.getSupportedCoordTypes();
209  },
210}
211```