> 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 settings are required**

`getCurrentLocation`You need to set location permission before using it. Please check the permission setup guide first.
{% endhint %}

***

### 1. Get current location

**SDK function:** `getCurrentLocation`

A function that retrieves the device's current location information only once. 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`

  An options object used when retrieving location information.

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

    It is the accuracy level for location information. For detailed values, please refer to the type below. `Accuracy` type below.

**Return value**

* `Promise<Location>`

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

**Permission methods**

* getCurrentLocation.getPermission

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

  Shows a dialog to request location permission again. If allowed `allowed`, if denied `denied`is returned.

**Error**

If 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 information 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 information 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`

A function that runs a callback every time the location changes. Use it in a fitness app to record travel distance or to update the location on a map in real time. Tracking stops when you call the returned cleanup function.

**Signature**

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

**Parameters**

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

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

  Callback function called when location detection fails.
* **options** · Required · `StartUpdateLocationOptions`

  Configuration object needed for location detection.

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

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

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

    Sets the location change distance in meters (m).

**Return value**

* () => void

  A 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

  Shows a dialog to request location permission again.

**Error**

If permission is denied `StartUpdateLocationPermissionError`occurs. `error instanceof StartUpdateLocationPermissionError`You can check it with

```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 %}

***

### Types · Objects

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

An enum for setting the location accuracy level.

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

***

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

An object that represents location information.

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

***

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

An object that 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; // direction
}
```


---

# 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.