RealtimeIRL Client API

An API to access RealtimeIRL data.

Installation

  npm install @rtirl/api

Alternatively, use it in the browser:

<script src="https://cdn.jsdelivr.net/npm/@rtirl/api@latest/lib/index.min.js"></script>

Usage

import * as RealtimeIRL from '@rtirl/api';

RealtimeIRL.forPullKey(YOUR_PULL_KEY).addLocationListener(function ({
  latitude,
  longitude,
}) {
  // do something with latitude/longitude
});

Firebase may fall back to long polling in some browser contexts. To force Realtime Database to use WebSockets, pass { forceWebSockets: true } on the first @rtirl/api call:

RealtimeIRL.forPullKey(YOUR_PULL_KEY, {
  forceWebSockets: true,
}).addLocationListener(function (location) {
  // do something with location.latitude/location.longitude
});

import * as RealtimeIRL from '@rtirl/api';

// muxfd = 158394109
RealtimeIRL.forStreamer("twitch", "158394109").addLocationListener(function (
  location
) {
  // do something with location.latitude/location.longitude
});

Public streamer locations also include reportedAt, the Unix timestamp in milliseconds for the coordinate update. Use @rtirl/api 1.2.4 or newer; earlier versions listen to the retired public location path.

See src/index.ts for all available functions and types.

Polling-based API

If you are interested in pulling the data in JSON format, the following endpoint is available:

GET https://rtirl.com/api/pull?key=<pull key>

The schema of the response depends on what fields have been pushed by the client. A sample output can be viewed here.

{
   "accuracy":5.408999919891357,  // meters
   "altitude":{
      "EGM96":3.5973978207728656, // meters
      "WGS84":-29.197977916731165 // meters
   },
   "heading":206.37741088867188,  // degrees
   "location":{
      "latitude":40.7047389,      // degrees
      "longitude":-74.0171302     // degrees
   },
   "reportedAt":1629924573000,    // milliseconds since epoch
   "speed":0.6116824746131897,    // meters per second
   "updatedAt":1629924573283      // milliseconds since epoch
}

Note that the polling API may update less frequently than the push API (~once per five seconds). If you wish to have realtime updates delivered as fast as possible, please use the push API. This helps us save on server costs.

Contributing

Contributions are always welcome! The documentation is currently quite sparse. Please feel free to send pull requests to improve them.