---
title: "Visual Localization"
slug: "arc-eye-vl-api"
tags: ["ARC eye"]
updated: 2026-09-17T10:05:44Z
published: 2026-09-17T10:05:44Z
canonical: "api.ncloud-docs.com/arc-eye-vl-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visual Localization

Available in Classic and VPC

Using information collected from vision devices, including cameras, you can check your current location even outdoors and indoors where GPS does not work, using only images. Additionally, it offers a location positioning service (WiFi Localization) that uses WiFi signal strength (RSSI) collected from the device to provide an approximate current location in indoor areas where GPS is unavailable. This allows for more accurate requests (radius search: lastPose + odometry combination) by providing both the approximate location of the device and location information.

              Note

              

See the following for information about the WiFi Localization feature.

- For more information about RSSI, see [Received signal strength indicator](https://en.wikipedia.org/wiki/Received_signal_strength_indicator).
- The WiFi Localization feature is not supported for spaces scanned before July 2024.

## Preliminary steps

The preliminary steps for using the ARC eye VL API are as follows:

### 1. Build spatial data

Build spatial data on the console. Proceed with all tasks in order, from SLAM data conversion to SLAM data merging, localization, and VL data conversion. For more information, see the [ARC eye user guide](https://guide.ncloud-docs.com/docs/en/arceye-overview).

### 2. Deploy API.

When VL data merging is successful, an API with a **Pending** status will be created in **Menu** > **All Services** > **Digital Twin** > **ARC eye** > **Visual Localization** > **API** of the NAVER Cloud Platform console. Select the API and deploy it. Once deployment is complete and the status is **Completed**, you can use the ARC eye VL API. You cannot deploy other APIs while the API service is **Stopped**. For more information on deployment, see the [ARC eye user guide](https://guide.ncloud-docs.com/docs/en/arceye-api).

## Request

This section describes the request format. The method and URI are as follows:

| Method | URI |
| --- | --- |
| POST | [InvokeURL](/docs/en/arc-eye-overview#APIURL) |

              Note

              

The `/api/vi~` path is the previous version of `/vl/v1/~`, which is the current version path.

### Request headers

For information about the headers common to all ARC eye APIs, see [ARC eye request headers](/docs/en/arc-eye-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### Request body

You can include the following data in the body of your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `image` | File | Required | Positioning target image - Can be omitted for WiFi requests |
| `cameraParameters` | String | Optional | Camera parameter information - Operate with default values when not entered. - fx, fy, cx, cy, k1, k2, p1, p2, k3 - fx, fy: Focal length of the camera lens - cx, cy: Principal point coordinates of the image sensor - k1, k2: Primary and secondary radial distortion correction coefficients of the lens - p1, p2: Tangential distortion correction coefficient of the lens - k3: Radial distortion correction coefficient of the lens |
| `lastPose` | String | Optional | 6-dof pose information estimated at the time of query image generation - Separated by commas. - Add `odometry` value to the most recent pose value received. - Required when using `odometry`. |
| `odometry` | String | Optional | Pose change between when the last query image was sent and when the current query image was sent - Separated by commas - Required when using `lastPose` |
| `withGlobal` | Boolean | Optional | How to interpret the `lastPose` value - `true` \| `false` - `true`: Interpret the `lastPose` value by "latitude, longitude, tz, qw, qx, qy, qz." - `false`: Interpret the `lastPose` value by "tx, ty, tz, qw, qx, qy, qz." |
| `withInlier` | Boolean | Optional | Whether to display the valid 3D-2D correspondences (3D space points and corresponding 2D image pixel coordinates) used for location positioning - `true` \| `false` - `true`: Display - `false`: Not display |
| `wifi` | File | Optional | WiFi signal strength scan file - JSON format |
| `datasetInfo` | String | Optional | Perform a VL query using only the processed data corresponding to the location layer name. - Location names are separated by commas. |

### Request example

The request example is as follows:

```
curl --location --request POST '{InvokeURL}' \
--header 'X-ARCEYE-SECRET: {SecretKey}' \
--header 'Content-Type: multipart/form-data' \
--form 'image=@location.jpg;type=image/jpeg' \
--form 'odometry=0,0,0,1,0,0,0' \
--form 'lastPose=0,0,0,1,0,0,0' \
--form 'cameraParameters=1186.7,1406.5,540,960,0.0,0.0,0.0,0.0,0.0' \
--form 'withInlier=true' \
--form 'datasetInfo=1F,T2B00652308180853'
```

## Response

This section describes the response format.

### Response body (success)

The following describes the response body when the query is successful.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `result` | String | - | Response result - `SUCCESS` \| `FAILURE` \| `ERROR` - `SUCCESS`: Succeeded - `FAILURE`: Failed - `ERROR`: Error |
| `status` | String | - | Response result status |
| `message` | String | - | Response result message |
| `tips` | String | - | Reference information for location positioning results |
| `pose` | String | - | Image name, tx, ty, tz, qw, qx, qy, qz values |
| `total` | Number | - | Total number of feature points extracted from the query image |
| `inlier` | Number | - | Total number of valid feature points extracted from the query image |
| `inliers` | Array | - | Valid 3D-2D correspondences information used for location positioning: [inliers](/docs/en/arc-eye-vl-api#inliers) |
| `residual` | Number | - | Projection error of valid features (in pixels) |
| `floor` | String | - | Floor information of the query image |
| `lonLat` | String | - | Longitude and latitude values |
| `globalPose` | String | - | Image name, longitude, latitude, altitude, qw, qx, qy, qz values |
| `nnPose` | Array | - | Image names of neighboring reference images, tx, ty, tz, qw, qx, qy, qz values |
| `datasetInfo` | String | - | A concatenation of the names of each layer separated by the scan |
| `confidence` | Number | - | Confidence value for estimated pose - Closer to 0 means less confidence, closer to 1 means more confidence. |
| `position` | String | - | Two-degree-of-freedom position value in mapping space (XY plane) |
| `datasetInfoScore` | String | - | Location classification accuracy - Closer to 0 means less confidence, closer to 1 means more confidence. |

#### `inliers`

The following describes `inliers`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `U` | Number | - | Pixel coordinates on 2D image |
| `V` | Number | - | Pixel coordinates on 2D image |
| `X` | Number | - | 3D X point |
| `Y` | Number | - | 3D Y point |
| `Z` | Number | - | 3D Z point |

### Response body (WiFi success)

The following describes the response body when the query via WiFi Localization is successful.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `result` | String | - | Response result - `SUCCESS` \| `FAILURE` - `SUCCESS`: Succeeded - `FAILURE`: Failed |
| `position` | String | - | Two-degree-of-freedom position value in mapping space (XY plane) |
| `lonLat` | String | - | Longitude and latitude values |
| `datasetInfo` | String | - | A concatenation of the names of each layer separated by the scan |
| `datasetInfoScore` | String | - | Location classification accuracy - Closer to 0 means less confidence, closer to 1 means more confidence. |

### Response body (failure)

The following describes the response body when the query fails.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `result` | String | - | Response result - `SUCCESS` \| `FAILURE` - `SUCCESS`: Succeeded - `FAILURE`: Failed |
| `status` | String | - | Response result status |
| `message` | String | - | Response result message |
| `pose` | String | - | Image name, tx, ty, tz, qw, qx, qy, qz values |
| `floor` | String | - | Floor information of the query image |
| `lonLat` | String | - | Longitude, latitude in order |
| `globalPose` | String | - | Image name, latitude, longitude, altitude, qw, qx, qy, qz values in order |
| `confidence` | Number | - | Confidence value for estimated pose - Closer to 0 means less confidence, closer to 1 means more confidence. |

### Response example

The response example is as follows:

#### Succeeded

The following is a sample response upon a successful query.

```
{
  "result": "SUCCESS",
  "status": "success",
  "message": "Localization successful",
  "tips": "",
  "pose": "VL0_0000050014880892_000000006.jpg,2.746507,9.889554,-20.729435,0.657244,-0.096816,-0.068169,0.744318",
  "total": 7738,
  "inlier": 1762,
  "inliers": [
    {
      "U": 356.8439,
      "V": 146.9978,
      "X": 114.01553,
      "Y": 233.33755,
      "Z": 12.9115095
    }
  ],
  "residual": 5.998124,
  "floor": "ground",
  "lonLat": "126.61787915108854,37.47318807235039",
  "globalPose": "VL0_0000050014880892_000000006.jpg,37.47318807235039,126.61787915108854,21.688565,0.657244,-0.096816,-0.068169,0.744318",
  "nnPoses" : [
      "40027089_1665033685979869.jpg,753.835632,-1213.756958,10.821537,-0.248478,0.098745,-0.0035,0.963585",
      "40027089_1652160158579869.jpg,734.655884,-1225.50354,11.025743,0.947723,0.057711,-0.073033,0.305217",
      ...
      "40027089_1652160155379869.jpg,732.119873,-1227.255127,11.040028,0.948575,0.056153,-0.07237,0.303009",
      "40027089_1652160158979869.jpg,734.967834,-1225.28418,11.024983,0.946591,0.057514,-0.07298,0.308759"
   ],
  "datasetInfo": "NationalMuseumKorea_1F_T2B00652308180853",
  "confidence": 0.834586441516876
}
```

#### Success (WiFi)

The following is a sample response when the query via WiFi Localization is successful.

```
{
  "result": "SUCCESS",
  "position": "16.6337711608804,5.690108685931897",
  "lonLat": "127.105412759367,37.359465269300976",
  "datasetInfo": "Naver_1784_1F",
  "datasetInfoScore": 0.6852494
}
```

#### Failure

The following is a sample response upon a failed query.

```
{
  "result": "FAILURE",
  "status": "success",
  "message": "Invalid parameters",
  "pose": "",
  "floor": "",
  "lonLat": "",
  "globalPose": "",
  "confidence": 0
}
```

              Note

              

For response bodies and response examples when API calls fail, see [ARC eye overview](/docs/en/arc-eye-overview#%EC%9D%91%EB%8B%B5).