Web SDK
This is the documentation for the web JavaScript SDK. Before integrating, read the native SDK documentation to familiarize yourself with the platform.
See the source on GitHub here. Or, see the radar-sdk-js
package on npm here.
#
InstallIn an HTML page, include the SDK using a <script>
tag:
<script src="https://js.radar.com/v3.6.1/radar.min.js"></script>
In a web app, install the package from npm, then import the library:
npm install --save radar-sdk-js
import Radar from 'radar-sdk-js';
The SDK is less than 20 KB minified.
#
Integrate#
InitializeTo initialize the library, call:
Radar.initialize(publishableKey);
where publishableKey
is a string containing your Radar publishable API key.
Optionally, to cache location updates for a period of time and avoid re-prompting for location,
provide a cacheLocationMinutes
value as an option when initializing:
Radar.initialize(publishableKey, { cacheLocationMinutes: 30});
#
Identify userTo 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 in cookies.
#
Foreground trackingOnce 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(function(err, result) { if (!err) { // do something with result.location, result.events, result.user }});
If the request is unsuccessful, err
will be a string, one of:
ERROR_PUBLISHABLE_KEY
: SDK not initializedERROR_PERMISSIONS
: location permissions not grantedERROR_LOCATION
: location services error or timeout (10 seconds)ERROR_NETWORK
: network error or timeout (10 seconds)ERROR_BAD_REQUEST
: bad request (missing or invalid params)ERROR_UNAUTHORIZED
: unauthorized (invalid API key)ERROR_PAYMENT_REQUIRED
: payment required (organization disabled or usage exceeded)ERROR_FORBIDDEN
: forbidden (insufficient permissions or no beta access)ERROR_NOT_FOUND
: not foundERROR_RATE_LIMIT
: too many requests (rate limit exceeded)ERROR_SERVER
: internal server errorERROR_UNKNOWN
: unknown error
#
Manual trackingYou can manually update the user's location by calling:
Radar.trackOnce({ latitude: 39.2904, longitude: -76.6122, accuracy: 65}, function(err, result) { if (!err) { // do something with result.events, result.user }});
#
Other APIsThe web SDK also exposes APIs for anonymous context, geocoding, search, and distance.
#
Get locationGet a single location update without sending it to the server:
Radar.getLocation(function(err, result) { if (!err) { // do something with result.location }});
#
ContextWith the context API, get context for a location without sending device or user identifiers to the server:
Radar.getContext({ latitude: 40.783826, longitude: -73.975363, accuracy: 65}, function(err, result) { if (!err) { // do something with result.context }});
#
GeocodingWith the forward geocoding API, geocode an address, converting address to coordinates:
Radar.geocode('20 jay st brooklyn ny', function(err, result) { if (!err) { // do something with result.addresses }});
With the reverse geocoding API, reverse geocode a location, converting coordinates to address:
Radar.reverseGeocode({ latitude: 40.783826, longitude: -73.975363}, function(err, result) { if (!err) { // do something with result.addresses }});
With the IP geocoding API, geocode the device's current IP address, converting IP address to city, state, and country:
Radar.ipGeocode(function(err, result) { if (!err) { // do something with result.address }});
#
SearchWith the autocomplete API, autocomplete partial addresses and place names, sorted by relevance:
Radar.autocomplete({ query: 'brooklyn roasting', near: { latitude: 40.783826, longitude: -73.975363 }, limit: 10}, function(err, result) { if (!err) { // do something with result.addresses }});
With the geofence search API, search for geofences near a location, sorted by distance:
Radar.searchGeofences({ radius: 1000, tags: ['venue'], limit: 10}, function(err, result) { if (!err) { // do something with result.geofences }});
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}, function(err, result) { if (!err) { // do something with result.places }});
With the address validation API (currently in beta), validate a structured address in the US or Canada:
Radar.validateAddress({ addressLabel: "841 Broadway Fl 7", city: "New York", stateCode: "NY", postalCode: "10003", countryCode: "US",}, function(err, { address, result }) { if (!err) { // do something with address and validation result }});
#
DistanceWith the distance API, calculate the travel distance and duration between two locations:
Radar.getDistance({ origin: { latitude: 40.78382, longitude: -73.97536 }, destination: { latitude: 40.70390, longitude: -73.98670 }, modes: [ 'foot', 'car' ], units: 'imperial'}, function(err, result) { if (!err) { // do something with result.routes }});
#
MatrixWith the matrix API, calculate the travel distances and durations between multiple origins and destinations for up to 25 routes:
Radar.getMatrix({ origins: [{ latitude: 40.70390, longitude: -73.98690 }], destinations: [{ latitude: 40.70390, longitude: -73.98690 }, { latitude: 40.73237, longitude: -73.94884 }], modes: 'car', units: 'imperial'}, function(err, result) { if (!err) { // do something with result.matrix }});
#
SupportHave questions? We're here to help! Email us at support@radar.com.