Web SDK

This is the documentation for the Radar Web SDK. The source can be found on GitHub here. Or, see the radar-sdk-js package on npm here.

Install

In an HTML page, add the SDK script:

<script src="https://js.radar.com/v5.1.0/radar.min.js"></script>

If you use Maps or Autocomplete UI, add the corresponding plugin scripts:

{/*  maps plugin (auto-registers)  */}
<link href="https://js.radar.com/maps/v1.0.0/radar-maps.css" rel="stylesheet">
<script src="https://js.radar.com/maps/v1.0.0/radar-maps.min.js"></script>

{/*  autocomplete plugin (auto-registers)  */}
<link href="https://js.radar.com/autocomplete/v1.0.0/radar-autocomplete.css" rel="stylesheet">
<script src="https://js.radar.com/autocomplete/v1.0.0/radar-autocomplete.min.js"></script>

In a web app, install the package from npm:

npm install radar-sdk-js

If you use Maps or Autocomplete UI, install the corresponding plugins:

# maps (requires maplibre-gl as a peer dep)
npm install @radarlabs/plugin-maps maplibre-gl

# autocomplete
npm install @radarlabs/plugin-autocomplete

Then, import the library and register any plugins:

import Radar from 'radar-sdk-js';

// for maps
import { createMapsPlugin } from '@radarlabs/plugin-maps';
import '@radarlabs/plugin-maps/dist/radar-maps.css';
Radar.registerPlugin(createMapsPlugin());

// for autocomplete
import { createAutocompletePlugin } from '@radarlabs/plugin-autocomplete';
import '@radarlabs/plugin-autocomplete/dist/radar-autocomplete.css';
Radar.registerPlugin(createAutocompletePlugin());

Setup

Initialize

Initialize the library with your publishable API key, found on the Settings page:

Radar.initialize('prj_live_pk_...');

You must initialize the library before calling any other functions.

Optionally, you can specify configuration options: The initialize call takes an optional second argument that is an object with additional configuration options.

Radar.initialize('prj_live_pk_...', { /* custom options here */});

Available options include:

Name	Default	Possible values	Description
`logLevel`	`error`	`none`, `info`, `warn`, `error`	Determines the log level for console logging. Defaults to `error` when using a test publishable key.
`cacheLocationMinutes`	`null`	number	Determines whether to reuse previous location updates. A cache ttl in minutes. If `null` or `0`, will always request a new location.
`locationMaximumAge`	`null`	number	Determines whether to use old browser locations. A maximum age in milliseconds. If `null` or `0`, will always request a new location. See getCurrentPosition options().
`locationTimeout`	`30000`	number	The number of milliseconds to wait for a location update before an error is thrown. Defaults to 30 seconds.
`networkTimeoutInterval`	`10`	number	The number of seconds to wait for a network request before an error is thrown.
`trackVerifiedAutoFailover`	`false`	`true`, `false`	Determines whether `Radar.trackVerified()` should automatically retry on the secondary verified host when the primary verified host fails. Requires `@radarlabs/plugin-fraud`.
`desiredAccuracy`	`high`	`high`, `medium`, `low`	Determines the desired accuracy of location updates. Note that higher accuracy can result in slower response times.
`debug`	`false`	`true`, `false`	Determines whether to include the raw API response body on results, as `response`. Defaults to `true` when using a test publishable key.

Geofencing

Identify user

To identify the user when logged in, call:

Radar.setUserId(userId);

where userId is a stable unique ID for the user. To set an optional dictionary of custom metadata for the user, call:

Radar.setMetadata(metadata);

where metadata is a JSON object with up to 16 keys and values of type string, boolean, or number. Finally, to set an optional description for the user, displayed in the dashboard, call:

Radar.setDescription(description);

where description is a string. You only need to call these functions once, as these settings will be persisted across browser sessions. Learn more about when Radar creates new user records here.

Foreground tracking

Once you have initialized the SDK and the user has granted permissions, you can track the user’s location. The SDK uses the HTML5 geolocation API to determine the user’s location. To track the user’s location, call:

Radar.trackOnce()
  .then((result) => {
    const { location, user, events } = result;
    // do something with location, user, or events
  })
  .catch((err) => {
    // handle error
  });

If the request fails, err will be one of:

RadarPublishableKeyError: SDK not initialized
RadarLocationPermissionsError: location permissions not granted
RadarLocationError: location services error or timeout (10 seconds)
RadarTimeoutError: network timeout (10 seconds)
RadarBadRequestError: bad request (missing or invalid params)
RadarUnknownError: unauthorized (invalid API key)
RadarPaymentRequiredError: payment required (organization disabled or usage exceeded)
RadarForbiddenError: forbidden (insufficient permissions or no beta access)
RadarNotFoundError: not found
RadarRateLimitError: too many requests (rate limit exceeded)
RadarServerError: internal server error
RadarUnknownError: unknown error

If the error is the result of a failed API call, err will include an HTTP response code and the API response body:

err.code; // HTTP response code
err.response; // API response body

Manual tracking

Alternatively, you can manually update the user’s location with any location by calling:

Radar.trackOnce({
  latitude: 39.2904,
  longitude: -76.6122,
  accuracy: 65
}).then((result) => {
  const { location, user, events } = result;
  // do something with location, user, or events
}).catch((err) => {
  // handle error
});

Maps

Geocoding

With the forward geocoding API, geocode an address, converting address to coordinates:

Radar.forwardGeocode({
  query: '841 broadway, new york, ny'
})
  .then((result) => {
    const { addresses } = result;
    // do something with addresses
  })
  .catch((err) => {
    // handle error
  });

With the reverse geocoding API, reverse geocode a location, converting coordinates to address:

Radar.reverseGeocode({
  latitude: 40.783826,
  longitude: -73.975363
})
  .then((result) => {
    const { addresses } = result;
    // do something with addresses
  })
  .catch((err) => {
    // handle error
  });

With the IP geocoding API, geocode the device’s current IP address, converting IP address to city, state, and country:

Radar.ipGeocode()
  .then((result) => {
    const { ip, address, proxy } = result;
    // do something with results
  })
  .catch((err) => {
    // handle error
  });

Search

With the autocomplete API, autocomplete partial addresses and place names, sorted by relevance:

Radar.autocomplete({
  query: '841 bro',
  near: {
    latitude: 40.783826,
    longitude: -73.975363
  },
  limit: 10
}).then((result) => {
  const { addresses } = result;
  // do something with addresses
}).catch((err) => {
  // handle error
});

With the geofence search API, search for geofences near a location, sorted by distance:

Radar.searchGeofences({
  radius: 1000,
  tags: ['venue'],
  limit: 10
}).then((result) => {
  const { geofences } = result;
  // do something with geofences
}).catch((err) => {
  // handle error
});

With the places search API, search for places near a location, sorted by distance:

Radar.searchPlaces({
  near: {
    latitude: 40.783826,
    longitude: -73.975363
  },
  radius: 1000,
  chains: ['starbucks'],
  limit: 10
}).then((result) => {
  const { places } = result;
  // do something with places
}).catch((err) => {
  // handle error
});

With the address validation API, validate a structured address in the US or Canada:

Radar.validateAddress({
  addressLabel: '841 BROADWAY',
  city: 'NEW YORK',
  stateCode: 'NY',
  postalCode: '10003',
  countryCode: 'US',
}).then((response) => {
  const { address, result } = response;
  // do something with validated address result
}).catch((err) => {
  // handle error
});

Distance

With the distance API, calculate the travel distance and duration between two locations:

Radar.distance({
  origin: {
    latitude: 40.78382,
    longitude: -73.97536
  },
  destination: {
    latitude: 40.70390,
    longitude: -73.98670
  },
  modes: [ 'foot', 'car' ],
  units: 'imperial'
}).then((result) => {
  const { routes } = result;
  const { geodesic, foot, bike, car } = routes;
  // do something with distance result
}).catch((err) => {
  // handle error
});

Matrix

With the matrix API, calculate the travel distances and durations between multiple origins and destinations for up to 25 routes:

Radar.matrix({
  origins: [{
    latitude: 40.70390,
    longitude: -73.98690
  }],
  destinations: [{
    latitude: 40.70390,
    longitude: -73.98690
  }, {
    latitude: 40.73237,
    longitude: -73.94884
  }],
  mode: 'car',
  units: 'imperial'
}).then((result) => {
  const { origins, destinations, matrix } = result;
  matrix.forEach((matrixResult) => {
    const { distance, duration, originIndex, destinationIndex } = matrixResult;
    // do something with matrix result
  });
}).catch((err) => {
  // handle error
});

Maps and UI kits

The React Native SDK also has UI components for maps and address autocomplete. Learn more in the Maps Platform documentation.

Request IDs

Every API response includes an X-Radar-Request-ID header with a unique identifier for the request. The Web SDK surfaces this identifier as meta.requestId on the API response body. If a request fails, get the request ID from the API response body on the error:

Radar.trackOnce()
  .catch((err) => {
    const requestId = err.response?.meta?.requestId;
  });

When the SDK is initialized with the debug option enabled, the API response body is also included on successful results, as response:

Radar.initialize('prj_live_pk_...', { debug: true });

Radar.trackOnce()
  .then((result) => {
    const requestId = result.response?.meta?.requestId;
  });

If you contact support about a specific API call, include the request ID. The request ID allows us to quickly find and debug the exact request.

Support

Have questions? We’re here to help! Contact us at radar.com/support.

Home

Geofencing Platform

Maps Platform

SDK Reference

API

Tutorials

Waypoint

FAQs

Install

Setup

Initialize

Geofencing

Identify user

Foreground tracking

Manual tracking

Maps

Geocoding

Search

Distance

Matrix

Maps and UI kits

Request IDs

Support

​Install

​Setup

​Initialize

​Geofencing

​Identify user

​Foreground tracking

​Manual tracking

​Maps

​Geocoding

​Search

​Distance

​Matrix

​Maps and UI kits

​Request IDs

​Support

Install

Setup

Initialize

Geofencing

Identify user

Foreground tracking

Manual tracking

Maps

Geocoding

Search

Distance

Matrix

Maps and UI kits

Request IDs

Support