ARC eye overview

Available in Classic and VPC

ARC eye is a NAVER Cloud Platform service that builds digital twin environments supporting positioning and object tracking for use in various fields such as AR, robots, and smart buildings. The ARC eye service provides APIs for visual localization (VL), visual object tracking (VOT), and query for map data to be used by robots in RESTful format.

Common ARC eye settings

The following describes commonly used request and response formats in ARC eye APIs.

Request

The following describes the common request format.

API URL

The request API URL is as follows:

API	API URL	Verification method
VL	Invoke URL displayed when you click [Check API integration key] in Menu > Services > Digital Twin > ARC eye > Visual Localization > API of the NAVER Cloud Platform console	Create API integration key and check invoke URL
VOT	Invoke URL displayed when you click [Check API integration key] in Menu > Services > Digital Twin > ARC eye > Visual Object Tracking > API of the NAVER Cloud Platform console	Create API integration key and check invoke URL
Map Data - Get download URL	Invoke URL displayed in the target Emapper or RobotMap task details in Menu > Services > Digital Twin > ARC eye > Visual Localization > Data Management of the NAVER Cloud Platform console
Map Data - Get location	Replace the last path `/download-urls` of the URL from Get download URL API with `/locations`.
Map Data - Get history	Replace the last path `/download-urls` of the URL from Get download URL API with `/versions`.

Request headers

The following describes the request headers.

Field	Required	Description
`X-ARCEYE-SECRET`	Required	Secret key issued by the ARC eye service VL: From the NAVER Cloud Platform console's Menu > Services > Digital Twin > ARC eye > Visual Localization > API, click [Check API integration key], and then click [Create] of Secret Key. VOT: From the NAVER Cloud Platform console's Menu > Services > Digital Twin > ARC eye > Visual Object Tracking > API, click [Check API integration key], and then click [Create] of Secret Key. Map Data: From the NAVER Cloud Platform console's Menu > Services > Digital Twin > ARC eye > Visual Localization > Data Management, click [Create] of Secret Key from the target Emapper or RobotMap task details.
`Content-Type`	Required	Response data format `multipart/form-data` Applicable for VL and VOT APIs (omitted for Map Data API since it is a GET request)

Note

Secret key of the Map Data API is issued and managed separately from the secret key of VL/VOT APIs. You can view the full value of the Map Data secret key only when it is first issued. Upon reissuance, the previous key expires immediately.

Response

The following describes the common response format.

Response body

For response bodies when a call is successful, see each API specification. The response body when the call fails is as follows:

Field	Type	Required	Description
`code`	String	-	Error code
`message`	String	-	Error message
`path`	String	-	Error occurrence path
`product`	String	-	Error service name
`traceId`	String	-	Error trace ID
`timestamp`	Long	-	Error occurrence time (millisecond) Unix timestamp format
`status`	Number	-	Response status codes
`details`	String	-	Error message detailed description
`errors`	String	-	Error data set information Visual Localization only
`errors.datasetInfo`	String	-	A concatenation of the names of each layer separated by the scan
`errors.datasetInfoScore`	String	-	Location classification accuracy Closer to 0 means less confidence, closer to 1 means more confidence.

Response status codes

The following describes the response status codes.

Visual Localization
The response status codes related to Visual Localization are as follows:

HTTP status code	Code	Message	Description
400	0100	there is no location	The location parameter is not passed.
400	0100	failed to parse wifi scan file	There is a problem with the entered WiFi scan data.
40x	0100	Invalid Parameter	Invalid request parameter
401	0020	Unauthorized	Invalid authentication information
403	0030	Forbidden	Unauthorized request
404	0001	Not Found	Non-existent resource
404	0100	failed to get location info from qdrant: xxx	Location information can't be obtained from the Qdrant DB.
404	0100	failed to get wifi-finder model file from S3	No processed WiFi finder model available
404	0100	wifi-loc model does not exists	No processed WiFi loc model available
409	0101	Duplicate	Duplicate request or resource
422	0100	failed, it has low dataset info score	No valid WiFi signal is available at the target location.
422	0100	failed to get location info from qdrant: xxx	Difficulty distinguishing locations due to low DatasetInfoScore
500	1000	No matching AP list exists	No WiFi signal with matching mac address
500	1000	failed to load qdrant	Unable to communicate with Qdrant vector DB
500	1000	failed to get global position filefrom qdrant	Global position information can't be obtained from the Qdrant.
500	1000	out of service, due to there is no valid xxx	An error occurred in internal server communication due to a lack of resources.
50x	1000	Internal API Error	Internal server error
500	1001	Processing Error	An error occurred while processing the request.
500	9999	Unknown Error	Unknown server error

Visual Object Tracking
The response status codes related to Visual Object Tracking are as follows:

HTTP status code	Code	Message	Description
404	0001	Not Found	Non-existent resource
401	0020	Unauthorized	Invalid authentication information
403	0030	Forbidden	Unauthorized request
40x	0100	Invalid Parameter	Invalid request parameter
409	0101	Duplicate	Duplicate request or resource
50x	1000	Internal API Error	Internal server error
500	1001	Processing Error	An error occurred while processing the request.
500	9999	Unknown Error	Unknown server error

Map Data
The following describes response status codes related to Map Data.

HTTP status code	Code	Message	Description
400	0100	Invalid parameters.	A value other than `emapper` or `robot-map` was passed to the `task` path variable.
401	0020	You don't have permission.	The signature value in the URL path is invalid.
401	0020	You don't have permission.	The `X-ARCEYE-SECRET` header is missing, or a secret key for Map Data has not been issued for this project.
401	0020	You don't have permission.	The value of the `X-ARCEYE-SECRET` header does not match the issued secret key.
404	0001	Does not exist.	The project with the requested `projectId` does not exist.
404	0001	Does not exist.	No conversion results exist for the requested `locationId`·`version` combination.
50x	1000	API error.	Internal server error
500	1001	Processing error.	An error occurred while processing the request.
500	9999	Unknown server error.	Unknown server error

Response example

For response examples when a call is successful, see each API specification. The following is a sample response upon a failed call.

VL API, VOT API call failure

{
  "code": "9999",
  "message": "Unknown server error.",
  "path": "/api/v1",
  "product": "ARC eye",
  "traceId": "9c1f55ac7d8341d792a922b2590c045f",
  "timestamp": 1570776853475,
  "status": "500"
}

VL (WiFi Localization) API call failure

{
  "traceId": "3d77c10b1a0646659b6c897a35a5fa64",
  "path": "/vl/v1/300568/9bb1a2b6f8031e355dfdb8e5205a1f7a860b167a0fcbd35681235f35c3629634/location",
  "timestamp": 1725449250446,
  "product": "ARC eye",
  "status": 422,
  "code": "0100",
  "message": "Invalid parameters.",
  "details": "there are no valid signals",
  "errors": { // optional
    "datasetInfo": "Naver_1784_1F",
    "datasetInfoScore": 0.6852494
  }
}

Map Data API call failure

{
  "code": "0020",
  "message": "You don't have permission.",
  "path": "/map-data/v1/300568/9bb1a2b6f8031e355dfdb8e5205a1f7a860b167a0fcbd35681235f35c3629634/robot-map/locations",
  "product": "ARC eye",
  "traceId": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
  "timestamp": 1745312000000,
  "status": 401
}

ARC eye API

The following describes the APIs provided by the ARC eye service.

API	Description
Visual Localization	Get location information.
Visual Object Tracking	Get object pose estimation result.
Map Data > Get location	Get the list of locations where e-map and robot map results exist.
Map Data > Get history	Get e-map and robot map conversion history (versions) for a specific location.
Map Data > Get download URL	Get the download URL for e-map and robot map results file for a specific location version.

ARC eye related resources

NAVER Cloud Platform provides a variety of related resources to help users better understand ARC eye APIs.

ARC eye service guides
- ARC eye user guide: How to use ARC eye in the NAVER Cloud Platform console
- Ncloud user environment guide: Explore VPC and Classic environments and supported services.
- Pricing and features: View pricing details, key capabilities, and utilization examples.
- Latest service news: The latest news on ARC eye
- FAQs: Get answers to common ARC eye questions.
- Contact Support: Get help if you can't find what you need in the user guide.