Create a geospatial anchor

post

https://platform.reactvision.xyz/functions/v1/geospatial-anchors

Client or secret key.

Creates an anchor at a GPS location, optionally linked to content: a whole Studio scene (scene_id), one placed asset of a scene with its transform (scene_asset_id), or a file uploaded with POST /assets/upload (user_asset_id). Linked content must belong to the anchor's project.

alt is the absolute altitude above sea level, not a height above the ground: see the field.

With a client key, project_id must be the key's project, and user_asset_id cannot be sent.

Counts as one request against the team's monthly API request quota, including a request that then fails a check.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

project_id

uuid

required

The project the anchor belongs to. With a client key the project must be the key's own project.

lat

number

required

-90 to 90

Latitude, -90 to 90. A number, not a string.

long

number

required

-180 to 180

Longitude, -180 to 180.

alt

number

-500 to 10000

Absolute altitude in meters above sea level, -500 to 10000. Default 0, which is sea level, not the ground: pass the real altitude. From a device, use the GPS altitude of the camera's geospatial pose; from coordinates, the terrain elevation plus the height above ground.

altitude_mode

string

enum

Stored and returned, but not interpreted by the AR runtime. Default street_level.

Allowed:

name

string

Cut to 150 characters.

description

string

Cut to 2000 characters.

scene_id

uuid

A whole Studio scene to show at the anchor. Must belong to the anchor's project.

scene_asset_id

uuid

One placed asset of a Studio scene, with its transform. Must belong to the anchor's project.

user_asset_id

uuid

A file uploaded with POST /assets/upload. Must belong to the anchor's project. A client key cannot send it.

mesh_url

string

World-mesh snapshot (.rvca), uploaded with asset_type=mesh. Must be the url that POST /assets/upload returned for this project's file.

Responses

`INVALID_BODY`: the body is not valid JSON, or not a JSON object.

`MISSING_FIELD`: `project_id`, `lat` or `long` is missing; the message names it.

`INVALID_LATITUDE`: `lat` is not a number from -90 to 90.

`INVALID_LONGITUDE`: `long` is not a number from -180 to 180.

`INVALID_ALTITUDE_MODE`: `altitude_mode` is not `street_level` or `rooftop_level`.

`INVALID_ALTITUDE`: `alt` is not a number from -500 to 10000.

`INVALID_MESH_URL`: `mesh_url` is not a mesh file this project uploaded.

`INVALID_FIELD_VALUE`: a client key sent `user_asset_id`.

`USER_ASSET_PROJECT_MISMATCH`: `user_asset_id` belongs to another project of the team.

Create a geospatial anchor

`PROJECT_NOT_FOUND`: `project_id` does not exist, belongs to another team, or is not the project the key is bound to. The three answers are the same.

`API_REQUEST_LIMIT_REACHED`: the team's monthly API request quota is used up.

`USER_ASSET_NOT_FOUND`: no such file, or one the key cannot reach.

`SCENE_NOT_FOUND`: no such scene in the project.

`SCENE_ASSET_NOT_FOUND`: no such scene asset in the project.

`RATE_LIMITED`: more than 30 a minute from one IP address for your team; or, for a secret key, more than 1,200 requests a minute across all operations. Wait the number of seconds in `Retry-After`. See Limits.

`CREATE_FAILED`: the anchor could not be stored.

`INTERNAL_ERROR`: an unexpected error. Retry, and quote `meta.request_id` to support if it persists.

`API_KEY_LOOKUP_FAILED`: the key could not be checked. Retry; this does not mean the key is invalid.

`PROJECT_LOOKUP_FAILED`: the project could not be checked. Retry.

201The anchor, without the linked-content objects.

401MISSING_API_KEY: no x-api-key header. INVALID_API_KEY_FORMAT: the key is not rv_live_, rv_client_ or rv_secret_ followed by 64 lowercase hexadecimal characters. INVALID_API_KEY: no such key, or a key sent with the wrong prefix for its type. API_KEY_EXPIRED: the key is past its expiry date.

403PROJECT_NOT_FOUND: project_id does not exist, belongs to another team, or is not the project the key is bound to. The three answers are the same. API_REQUEST_LIMIT_REACHED: the team's monthly API request quota is used up.

404USER_ASSET_NOT_FOUND: no such file, or one the key cannot reach. SCENE_NOT_FOUND: no such scene in the project. SCENE_ASSET_NOT_FOUND: no such scene asset in the project.

429RATE_LIMITED: more than 30 a minute from one IP address for your team; or, for a secret key, more than 1,200 requests a minute across all operations. Wait the number of seconds in Retry-After. See Limits.

500CREATE_FAILED: the anchor could not be stored. INTERNAL_ERROR: an unexpected error. Retry, and quote meta.request_id to support if it persists.

503API_KEY_LOOKUP_FAILED: the key could not be checked. Retry; this does not mean the key is invalid. PROJECT_LOOKUP_FAILED: the project could not be checked. Retry.

`PROJECT_NOT_FOUND`: `project_id` does not exist, belongs to another team, or is not the project the key is bound to. The three answers are the same.

`API_REQUEST_LIMIT_REACHED`: the team's monthly API request quota is used up.

`USER_ASSET_NOT_FOUND`: no such file, or one the key cannot reach.

`SCENE_NOT_FOUND`: no such scene in the project.

`SCENE_ASSET_NOT_FOUND`: no such scene asset in the project.

`RATE_LIMITED`: more than 30 a minute from one IP address for your team; or, for a secret key, more than 1,200 requests a minute across all operations. Wait the number of seconds in `Retry-After`. See Limits.

`CREATE_FAILED`: the anchor could not be stored.

`INTERNAL_ERROR`: an unexpected error. Retry, and quote `meta.request_id` to support if it persists.

`API_KEY_LOOKUP_FAILED`: the key could not be checked. Retry; this does not mean the key is invalid.

`PROJECT_LOOKUP_FAILED`: the project could not be checked. Retry.