Skip to main content

Location

Read GPS coordinates and compass heading on SPECS with the Location API to build location-aware Lenses.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
  • SnapchatNot supported
  • SPECSFully supported
  • Camera Kit WebNot supported
  • Camera Kit MobileNot supported

Platform details

  • Snapchat — Not supported.

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported.

  • Camera Kit Mobile — Not supported.

Overview

On SPECS, the Location API gives a Lens the device's GPS coordinates and its heading, for location-based experiences such as outdoor navigation and points of interest.

To use location services on SPECS, users must be signed in and paired with their SPECS account, with location permission turned on. They should also be connected to the internet.

Set up a Lens to use location on SPECS

Requirements for the Location API

  • Lens Studio 5.25 or later
  • SPECS 27

Declare the RawLocationModule permission

To use the Location API on SPECS, declare that your Lens uses the RawLocationModule permission by requiring it in a script. For how permissions are declared, see Permissions Overview.

require('LensStudio:RawLocationModule');

Get the user's location and heading on SPECS

A Lens reads location through the Location Service API. getCurrentPosition returns the user's current position, and onNorthAlignedOrientationUpdate reports their heading as a north-aligned orientation (a quaternion), with the heading's accuracy as a second argument.

Choose the accuracy your use case needs with GeoLocationAccuracy. On SPECS, accuracy depends on the environment (rural or urban):

AccuracyOn SPECS
NavigationFor guiding the user in navigation. Generally accurate up to 20 meters. Enables the FUSED_LOCATION location source, available at rendering rate when reception is good; otherwise one update every 10 seconds.
HighGood accuracy without the navigation requirement, with lower waiting times. Generally accurate up to 30 meters. One update per second in good conditions, otherwise one every 10 seconds.
MediumPower efficient. Generally accurate up to 30 meters. One update every 15 seconds.
LowThe most power efficient. Generally accurate up to 100 meters. One update every 30 seconds.

Heading accuracy improves as the user walks around, because SPECS calibrates the heading automatically.

Example: log location and heading

require('LensStudio:RawLocationModule');

@component
export class LocationExample extends BaseScriptComponent {
latitude: number;
longitude: number;
altitude: number;
horizontalAccuracy: number;
verticalAccuracy: number;
timestamp: Date;
locationSource: string;

private repeatUpdateUserLocation: DelayedCallbackEvent;
private locationService: LocationService;
onAwake() {
this.createEvent('OnStartEvent').bind(() => {
this.createAndLogLocationAndHeading();
});

this.repeatUpdateUserLocation = this.createEvent('DelayedCallbackEvent');
this.repeatUpdateUserLocation.bind(() => {
// Get users location.
// Arrow functions keep `this` bound to the component.
this.locationService.getCurrentPosition(
(geoPosition) => {
//Check if location coordinates have been updated based on timestamp
if (
this.timestamp === undefined ||
this.timestamp.getTime() != geoPosition.timestamp.getTime()
) {
this.latitude = geoPosition.latitude;
this.longitude = geoPosition.longitude;
this.horizontalAccuracy = geoPosition.horizontalAccuracy;
this.verticalAccuracy = geoPosition.verticalAccuracy;
print('long: ' + this.longitude);
print('lat: ' + this.latitude);
if (geoPosition.altitude != 0) {
this.altitude = geoPosition.altitude;
print('altitude: ' + this.altitude);
}
this.locationSource = geoPosition.locationSource;
print('location source: ' + this.locationSource);
this.timestamp = geoPosition.timestamp;
}
},
(error) => {
print(error);
}
);
// Acquire next location update in 1 second, increase this value if required for AR visualisation purposes such as 0.5 or 0.1 seconds
this.repeatUpdateUserLocation.reset(1.0);
});
}
createAndLogLocationAndHeading() {
// Create location handler
this.locationService = GeoLocation.createLocationService();

// Set the accuracy
this.locationService.accuracy = GeoLocationAccuracy.Navigation;

// Acquire heading orientation updates
var onOrientationUpdate = function (northAlignedOrientation) {
//Providing 3DoF north aligned rotation in quaternion form
let heading = GeoLocation.getNorthAlignedHeading(northAlignedOrientation);
print('Heading orientation: ' + heading.toFixed(3));
// Convert to a 2DoF rotation for plane rendering purposes
var rotation = (heading * Math.PI) / 180;
print(
'Screen transform rotation: ' + quat.fromEulerAngles(0, 0, rotation)
);
};
this.locationService.onNorthAlignedOrientationUpdate.add(
onOrientationUpdate
);

// Acquire next location immediately with zero delay
this.repeatUpdateUserLocation.reset(0.0);
}
}

Show location and heading on a map and in AR

The Outdoor Navigation sample, in the Spectacles (2024) samples repository on GitHub, is an example of giving directions with location and heading. It shows content on a 2D map or in an AR view.

The Outdoor Navigation 2D map

The Outdoor Navigation sample's 2D map component zooms and scrolls a 2D map, follows the user, lets users drop pins by hand, generates points of interest automatically with the Snap Places API, and shows the same content in the AR view at the same time. The Snap Places API brings Snapchat map features into a Lens, so users can interact with nearby places.

Generating pins automatically combines the Snap Places API, which runs over the Remote Service Module, with the Location Service (RawLocationModule). That combination is publishable through Transparent Permission: the Lens asks the user for permission at launch.

The Outdoor Navigation AR view

The Outdoor Navigation sample's AR view shows points of interest in AR. It is built from these parts, all provided in the sample:

  1. Navigation accuracy : Requires selecting Navigation accuracy level within the LocationService. This ensures that the AR features align accurately with the user's geographical position.
  2. Location Source : The AR view will benefit from utilizing a FUSED_LOCATION source, which combines various location signals for optimal accuracy and reliability. This is activated automatically when selecting Navigation accuracy.
  3. 6DoF Pose : Utilizes latitude, longitude, altitude, and north-aligned orientation to create a six degrees of freedom (6DoF) pose, allowing for precise rendering of AR content.
  4. Pins on 2D Map : Users can create pins by hand, or the Snap Places API can add them automatically. Combined with the Location Service, the Snap Places API is publishable through Transparent Permission.
  5. AR View Visuals :
    • Displays existing pins from the 2D map.
    • Provides directional guidance via white arrows to point the user towards the points of interest.
    • Shows a red dot when a point of interest should be in view.
    • Displays the distance from the user to these points of interest.

For the implementation details, see the Outdoor Navigation sample.

Filter nearby places by category

With the Snap Places API and location services, you can filter nearby places by category. The Outdoor Navigation sample's showNearbyPlaces() method takes an array of category names and shows only places of those types.

Show nearby places by category

These examples call the MapComponent script in the Outdoor Navigation sample; see that script for the complete implementation.

// Show all nearby places (pass null or empty array)
this.mapComponent.showNearbyPlaces(null);

// Show specific categories
this.mapComponent.showNearbyPlaces(['Restaurant']);
this.mapComponent.showNearbyPlaces(['Coffee Shop', 'Café']);
this.mapComponent.showNearbyPlaces(['Bar', 'Pub']);

// Show multiple related categories
this.mapComponent.showNearbyPlaces([
'Restaurant',
'Fast Food Restaurant',
'Pizza Restaurant',
]);

Location categories for the Places API

This table lists every location category the Places API accepts. Pass the Category Name values to showNearbyPlaces():

Category NameCategory Path
RestaurantFood & Beverage / Eatery / Restaurant
Fast Food RestaurantFood & Beverage / Eatery / Fast Food Restaurant
Pizza RestaurantFood & Beverage / Eatery / Pizza Restaurant
Chinese RestaurantFood & Beverage / Eatery / Asian Cuisine / Chinese Restaurant
Mexican RestaurantFood & Beverage / Eatery / Mexican Cuisine / Mexican Restaurant
Italian RestaurantFood & Beverage / Eatery / European Cuisine / Italian Restaurant
Burger RestaurantFood & Beverage / Eatery / American Cuisine / Burger Restaurant
CaféFood & Beverage / Eatery / Café
Coffee ShopFood & Beverage / Non-Alcoholic Beverages / Coffee Shop
BakeryFood & Beverage / Eatery / Bakery
Grocery StoreShops & Services / Retail / Food Store / Grocery Store
Convenience StoreShops & Services / Retail / Convenience Store
BankShops & Services / Service / Financial & Legal Services / Bank
Gas StationTravel / Transportation / Automotive / Gas Station
ParkingTravel / Transportation / Automotive / Parking
HotelTravel / Lodging / Hotel
Shopping MallShops & Services / Retail / Shopping Mall
Beauty SalonShops & Services / Service / Beauty & Personal Care / Beauty Salon
Auto GarageShops & Services / Service / Automotive / Auto Garage
Car WashShops & Services / Service / Automotive / Car Wash
Movie TheaterArts & Entertainment / Movie Theaters / Movie Theater
MuseumArts & Entertainment / Museums / Museum
LibraryOther / Civic / Community & Government / Library
Post OfficeOther / Civic / Community & Government / Post Office
Police StationOther / Civic / Community & Government / Police Station
GymOutdoors & Recreation / Recreation / Gym
ParkOutdoors & Recreation / Outdoors / Parks / Park
AirportTravel / Transportation / Aviation / Airport
Train StationTravel / Transportation / Rail Transit / Train Station
Bus StationTravel / Transportation / Bus Transit / Bus Station
Electronics StoreShops & Services / Retail / Electronics Store
Clothing StoreShops & Services / Retail / Apparel and Accessories / Clothing Store
Department StoreShops & Services / Retail / Apparel and Accessories / Department Store
Hardware StoreShops & Services / Retail / Hardware Store
ChurchReligion / Church
High SchoolEducation / High School
Amusement ParkArts & Entertainment / Amusement Park
ZooArts & Entertainment / Zoo
BeachOutdoors & Recreation / Outdoors / Swimming / Beach
Golf CourseOutdoors & Recreation / Recreation / Golf Course
Tourist AttractionOutdoors & Recreation / Attraction / Tourist Attraction
City HallOther / Civic / Community & Government / City Hall
Bus StopTravel / Transportation / Bus Transit / Bus Stop
Pet StoreShops & Services / Retail / Pet Store
BookstoreShops & Services / Retail / Bookstore
StadiumArts & Entertainment / Stadiums and Arenas / Stadium
LaundromatShops & Services / Service / Laundromat

Showing 47 of 47 categories

You can combine multiple category names in a single call to showNearbyPlaces() to show different types of related places simultaneously. For example, ["Restaurant", "Café", "Bar"] will show all food and beverage establishments.

Passing null or an empty array to showNearbyPlaces() will return all available place categories in the area, which may result in a large number of pins on your map.

Known limitations of location and heading on SPECS

Location

  • Without an internet connection, the Lens can take a moment to initialize and provide location data the first time it runs.
  • Navigation accuracy can degrade at night.

Heading

  • After a Snap OS update, the heading can take a moment to initialize, because a calibration runs in the background, invisible to the user. To speed it up:
    1. Right after the Snap OS update, wear SPECS with the display on.
    2. Rotate the device for about 20 seconds: look around, turn around, and look up and down to cover several directions.