> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/permission/location.md).

# Location

{% hint style="info" %}
**Permission setup is required**

`getCurrentLocation`Before using it, you need to set location permissions. Please check the permission setup guide first.
{% endhint %}

***

### 1. Get current location

**SDK function:** `getCurrentLocation`

This function gets the device's current location information only once. It's useful for showing the user's location on a map or searching for nearby stores.

**Signature**

```typescript
function getCurrentLocation(options: { accuracy: Accuracy }): Promise<Location>;
```

**Parameters**

* **options** · Required · `object`

  This is the options object used when getting location information.

  * **options.accuracy** · Required · `Accuracy`

    This is the accuracy level of the location information. For detailed values, see the `Accuracy` type below.

**Return value**

* `Promise<Location>`

  Returns an object containing the device's location information. For details, see the `Location` type below.

**Permission methods**

* getCurrentLocation.getPermission

  Returns the current status of location permission. `allowed` · `denied` · `notDetermined` · `osPermissionDenied` Returns one of these.
* getCurrentLocation.openPermissionDialog

  Displays a dialog to request location permission again. If you allow it, `allowed`, if you deny it, `denied`is returned.

**Error**

When permission is denied `GetCurrentLocationPermissionError`occurs.

```typescript
class GetCurrentLocationPermissionError extends PermissionError {
  constructor();
}
```

**Example**

{% tabs %}
{% tab title="Web (JS)" %}

```js
import { Accuracy, getCurrentLocation, GetCurrentLocationPermissionError } from '@apps-in-toss/web-framework';

async function handleGetCurrentLocation() {
  try {
    const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
    console.log(`Location: ${response.coords.latitude}, ${response.coords.longitude}`);
  } catch (error) {
    if (error instanceof GetCurrentLocationPermissionError) {
      console.log('No location permission');
    }
  }
}
```

{% endtab %}

{% tab title="Web (React)" %}

```tsx
import { Accuracy, getCurrentLocation, GetCurrentLocationPermissionError, Location } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function CurrentPosition() {
  const [position, setPosition] = useState<Location | null>(null);

  const handlePress = async () => {
    try {
      const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
      setPosition(response);
    } catch (error) {
      if (error instanceof GetCurrentLocationPermissionError) {
        // No location permission
      }
    }
  };

  return (
    <div>
      {position ? (
        <span>
          Location: {position.coords.latitude}, {position.coords.longitude}
        </span>
      ) : (
        <span>Location has not been retrieved yet</span>
      )}
      <input type="button" value="Get current location" onClick={handlePress} />
      <input
        type="button"
        value="Check permission"
        onClick={async () => alert(await getCurrentLocation.getPermission())}
      />
      <input
        type="button"
        value="Request permission"
        onClick={async () => alert(await getCurrentLocation.openPermissionDialog())}
      />

  );
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Accuracy, getCurrentLocation, GetCurrentLocationPermissionError, Location } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

function CurrentPosition() {
  const [position, setPosition] = useState<Location | null>(null);

  const handlePress = async () => {
    try {
      const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
      setPosition(response);
    } catch (error) {
      if (error instanceof GetCurrentLocationPermissionError) {
        // No location permission
      }
    }
  };

  return (
    <View>
      {position ? (
        <Text>
          Location: {position.coords.latitude}, {position.coords.longitude}
        </Text>
      ) : (
        <Text>Location has not been retrieved yet</Text>
      )}
      <Button title="Get current location" onPress={handlePress} />
      <Button title="Check permission" onPress={async () => Alert.alert(await getCurrentLocation.getPermission())} />
      <Button
        title="Request permission"
        onPress={async () => Alert.alert(await getCurrentLocation.openPermissionDialog())}
      />
    </View>
  );
}
```

{% endtab %}
{% endtabs %}

***

### 2. Track location in real time

**SDK function:** `startUpdateLocation`

This function runs a callback every time the location changes. It's used in fitness apps to record distance traveled or to update the location in real time on a map. Calling the returned cleanup function stops tracking.

**Signature**

```typescript
function startUpdateLocation(options: {
  onError: (error: unknown) => void;
  onEvent: (location: Location) => void;
  options: StartUpdateLocationOptions;
}): () => void;
```

**Parameters**

* **onEvent** · Required · `(location: Location) => void`

  This is the callback function called when location information changes.
* **onError** · Required · `(error: unknown) => void`

  This is the callback function called when location detection fails.
* **options** · Required · `StartUpdateLocationOptions`

  This is the configuration object required for location detection.

  * **options.accuracy** · `Accuracy`

    Sets the location accuracy.
  * **options.timeInterval** · `number`

    The minimum interval for updating location information. The unit is milliseconds (ms).
  * **options.distanceInterval** · `number`

    Sets the distance threshold for location changes in meters (m).

**Return value**

* () => void

  This is the cleanup function that stops location tracking. Be sure to call it when the component unmounts.

**Permission methods**

* startUpdateLocation.getPermission

  Returns the current status of location permission.
* startUpdateLocation.openPermissionDialog

  Displays a dialog to request location permission again.

**Error**

When permission is denied `StartUpdateLocationPermissionError`occurs. `error instanceof StartUpdateLocationPermissionError`can be checked with this.

```typescript
const StartUpdateLocationPermissionError: typeof GetCurrentLocationPermissionError;
```

**Example**

{% tabs %}
{% tab title="Web (JS)" %}

```js
import { Accuracy, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/web-framework';

let cleanup;

function handleStartUpdateLocation() {
  cleanup?.();

  cleanup = startUpdateLocation({
    options: { accuracy: Accuracy.Balanced, timeInterval: 3000, distanceInterval: 10 },
    onEvent: (location) => {
      console.log(`Latitude: ${location.coords.latitude}, Longitude: ${location.coords.longitude}`);
    },
    onError: (error) => {
      if (error instanceof StartUpdateLocationPermissionError) {
        console.log('No location permission');
      }
    },
  });
}

window.addEventListener('pagehide', () => cleanup?.());
```

{% endtab %}

{% tab title="Web (React)" %}

```tsx
import {
  Accuracy,
  Location,
  startUpdateLocation,
  StartUpdateLocationPermissionError,
} from '@apps-in-toss/web-framework';
import { useCallback, useState } from 'react';

function LocationWatcher() {
  const [location, setLocation] = useState<Location | null>(null);

  const handlePress = useCallback(() => {
    startUpdateLocation({
      options: { accuracy: Accuracy.Balanced, timeInterval: 3000, distanceInterval: 10 },
      onEvent: (location) => setLocation(location),
      onError: (error) => {
        if (error instanceof StartUpdateLocationPermissionError) {
          // No location permission
        }
      },
    });
  }, []);

  return (
    <div>
      {location != null && (
        <>
          <span>Latitude: {location.coords.latitude}</span>
          <span>Longitude: {location.coords.longitude}</span>
        </>
      )}
      <input type="button" value="Start location tracking" onClick={handlePress} />

  );
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Accuracy, Location, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/framework';
import { useCallback, useState } from 'react';
import { Button, Text, View } from 'react-native';

function LocationWatcher() {
  const [location, setLocation] = useState<Location | null>(null);

  const handlePress = useCallback(() => {
    startUpdateLocation({
      options: { accuracy: Accuracy.Balanced, timeInterval: 3000, distanceInterval: 10 },
      onEvent: (location) => setLocation(location),
      onError: (error) => {
        if (error instanceof StartUpdateLocationPermissionError) {
          // No location permission
        }
      },
    });
  }, []);

  return (
    <View>
      {location != null && (
        <>
          <Text>Latitude: {location.coords.latitude}</Text>
          <Text>Longitude: {location.coords.longitude}</Text>
        </>
      )}
      <Button title="Start location tracking" onPress={handlePress} />
    </View>
  );
}
```

{% endtab %}
{% endtabs %}

***

### Type · Object

**Location accuracy options (`Accuracy`)**

This is an enum for setting the location accuracy level.

```typescript
enum Accuracy {
  Lowest = 1, // within 3 km error range
  Low = 2, // within 1 km error range
  Balanced = 3, // within a few hundred meters error range
  High = 4, // within 10 m error range
  Highest = 5, // highest accuracy
  BestForNavigation = 6, // best accuracy for navigation
}
```

***

**Location information object (`Location`)**

This object represents location information.

```typescript
interface Location {
  accessLocation?: 'FINE' | 'COARSE'; // Android only. FINE: precise location, COARSE: approximate location
  timestamp: number; // Unix timestamp of when the location was updated
  coords: LocationCoords; // detailed coordinate information
}
```

***

**Detailed location coordinate information (`LocationCoords`)**

This object represents detailed location coordinate information.

```typescript
interface LocationCoords {
  latitude: number; // latitude
  longitude: number; // longitude
  altitude: number; // altitude
  accuracy: number; // location accuracy
  altitudeAccuracy: number; // altitude accuracy
  heading: number; // heading
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/permission/location.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.