> 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/common/permission/location.md).

# 위치

{% hint style="info" %}
**권한 설정이 필요해요**

`getCurrentLocation`를 사용하기 전에 위치 권한을 설정해야 해요. 권한 설정 가이드를 먼저 확인해 주세요.
{% endhint %}

***

### 1. 현재 위치 가져오기

**SDK 함수:** `getCurrentLocation`

디바이스의 현재 위치 정보를 한 번만 가져오는 함수예요. 지도에서 사용자 위치를 표시하거나, 가까운 매장을 검색할 때 유용해요.

**시그니처**

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

**파라미터**

* **options** · 필수 · `object`

  위치 정보를 가져올 때 사용하는 옵션 객체예요.

  * **options.accuracy** · 필수 · `Accuracy`

    위치 정보의 정확도 수준이에요. 자세한 값은 아래 `Accuracy` 타입을 참고해 주세요.

**반환값**

* `Promise<Location>`

  디바이스의 위치 정보가 담긴 객체를 반환해요. 자세한 내용은 아래 `Location` 타입을 참고해 주세요.

**권한 메서드**

* getCurrentLocation.getPermission

  위치 정보 권한의 현재 상태를 반환해요. `allowed` · `denied` · `notDetermined` · `osPermissionDenied` 중 하나를 반환해요.
* getCurrentLocation.openPermissionDialog

  위치 정보 권한을 다시 요청하는 다이얼로그를 표시해요. 허용하면 `allowed`, 거부하면 `denied`를 반환해요.

**에러**

권한이 거부된 경우 `GetCurrentLocationPermissionError`가 발생해요.

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

**예제**

{% 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(`위치: ${response.coords.latitude}, ${response.coords.longitude}`);
  } catch (error) {
    if (error instanceof GetCurrentLocationPermissionError) {
      console.log('위치 정보 권한 없음');
    }
  }
}
```

{% 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) {
        // 위치 정보 권한 없음
      }
    }
  };

  return (
    <div>
      {position ? (
        <span>
          위치: {position.coords.latitude}, {position.coords.longitude}
        </span>
      ) : (
        <span>위치 정보를 아직 가져오지 않았어요</span>
      )}
      <input type="button" value="현재 위치 가져오기" onClick={handlePress} />
      <input
        type="button"
        value="권한 확인하기"
        onClick={async () => alert(await getCurrentLocation.getPermission())}
      />
      <input
        type="button"
        value="권한 요청하기"
        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) {
        // 위치 정보 권한 없음
      }
    }
  };

  return (
    <View>
      {position ? (
        <Text>
          위치: {position.coords.latitude}, {position.coords.longitude}
        </Text>
      ) : (
        <Text>위치 정보를 아직 가져오지 않았어요</Text>
      )}
      <Button title="현재 위치 가져오기" onPress={handlePress} />
      <Button title="권한 확인하기" onPress={async () => Alert.alert(await getCurrentLocation.getPermission())} />
      <Button
        title="권한 요청하기"
        onPress={async () => Alert.alert(await getCurrentLocation.openPermissionDialog())}
      />
    </View>
  );
}
```

{% endtab %}
{% endtabs %}

***

### 2. 실시간 위치 추적하기

**SDK 함수:** `startUpdateLocation`

위치가 변경될 때마다 콜백을 실행하는 함수예요. 운동 앱에서 이동 거리를 기록하거나 지도에서 위치를 실시간으로 업데이트할 때 사용해요. 반환된 cleanup 함수를 호출하면 추적이 중단돼요.

**시그니처**

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

**파라미터**

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

  위치 정보가 변경될 때 호출되는 콜백 함수예요.
* **onError** · 필수 · `(error: unknown) => void`

  위치 정보 감지에 실패했을 때 호출되는 콜백 함수예요.
* **options** · 필수 · `StartUpdateLocationOptions`

  위치 정보 감지에 필요한 설정 객체예요.

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

    위치 정확도를 설정해요.
  * **options.timeInterval** · `number`

    위치 정보를 업데이트하는 최소 주기예요. 단위는 밀리초(ms)예요.
  * **options.distanceInterval** · `number`

    위치 변경 거리를 미터(m) 단위로 설정해요.

**반환값**

* () => void

  위치 추적을 중단하는 cleanup 함수예요. 컴포넌트 언마운트 시 반드시 호출해 주세요.

**권한 메서드**

* startUpdateLocation.getPermission

  위치 정보 권한의 현재 상태를 반환해요.
* startUpdateLocation.openPermissionDialog

  위치 정보 권한을 다시 요청하는 다이얼로그를 표시해요.

**에러**

권한이 거부된 경우 `StartUpdateLocationPermissionError`가 발생해요. `error instanceof StartUpdateLocationPermissionError`로 확인할 수 있어요.

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

**예제**

{% 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(`위도: ${location.coords.latitude}, 경도: ${location.coords.longitude}`);
    },
    onError: (error) => {
      if (error instanceof StartUpdateLocationPermissionError) {
        console.log('위치 정보 권한 없음');
      }
    },
  });
}

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) {
          // 위치 정보 권한 없음
        }
      },
    });
  }, []);

  return (
    <div>
      {location != null && (
        <>
          <span>위도: {location.coords.latitude}</span>
          <span>경도: {location.coords.longitude}</span>
        </>
      )}
      <input type="button" value="위치 추적 시작" 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) {
          // 위치 정보 권한 없음
        }
      },
    });
  }, []);

  return (
    <View>
      {location != null && (
        <>
          <Text>위도: {location.coords.latitude}</Text>
          <Text>경도: {location.coords.longitude}</Text>
        </>
      )}
      <Button title="위치 추적 시작" onPress={handlePress} />
    </View>
  );
}
```

{% endtab %}
{% endtabs %}

***

### 타입 · 객체

**위치 정확도 옵션 (`Accuracy`)**

위치 정확도 수준을 설정하는 enum이에요.

```typescript
enum Accuracy {
  Lowest = 1, // 오차범위 3KM 이내
  Low = 2, // 오차범위 1KM 이내
  Balanced = 3, // 오차범위 몇 백미터 이내
  High = 4, // 오차범위 10M 이내
  Highest = 5, // 가장 높은 정확도
  BestForNavigation = 6, // 네비게이션을 위한 최고 정확도
}
```

***

**위치 정보 객체 (`Location`)**

위치 정보를 나타내는 객체예요.

```typescript
interface Location {
  accessLocation?: 'FINE' | 'COARSE'; // Android 전용. FINE: 정확한 위치, COARSE: 대략적인 위치
  timestamp: number; // 위치가 업데이트된 시점의 유닉스 타임스탬프
  coords: LocationCoords; // 세부 좌표 정보
}
```

***

**세부 위치 좌표 정보 (`LocationCoords`)**

세부 위치 좌표 정보를 나타내는 객체예요.

```typescript
interface LocationCoords {
  latitude: number; // 위도
  longitude: number; // 경도
  altitude: number; // 높이
  accuracy: number; // 위치 정확도
  altitudeAccuracy: number; // 고도 정확도
  heading: number; // 방향
}
```


---

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