Skip to main content
Version: 2.0.0

Call an external API from your module

Prerequisites

You need a module and a client connected to it. If you don't have them yet, follow the quickstart for your language first. This guide uses Open-Meteo, a weather API you can call without an API key. Its free API is for non-commercial use, so check its terms before you ship.

There's no C++ version of this guide yet.

In this guide, you'll show live weather in your game world, from a weather API. Your module fetches the weather on a schedule and stores it in a public table, so every client gets it through a subscription, and you make one request per refresh, however many players are connected. You'll make the request from a procedure, call it with a schedule table, and start it from the init lifecycle reducer.

How it works​

  • A public weather table has a single row with the latest weather: the temperature, a weather code, and when it was fetched.
  • A private weather_refresh schedule table calls the refresh_weather procedure every 15 minutes. The init reducer inserts its rows when the database is created.
  • refresh_weather fetches the current weather from the API, then stores it in weather.
  • If the request fails, weather keeps the last weather, and the next refresh tries again.
  • Clients subscribe to weather, and update what they show when it changes.

The request is made from a procedure, not a reducer. Reducers can't make HTTP requests, because they run inside a transaction. A procedure makes the request outside of any transaction, then stores the result in a short one.

Define the tables​

Add two tables:

  • weather holds the latest weather, in a single row with id 0. It's public, so clients can subscribe to it.
  • weather_refresh is the schedule table. Its scheduled_at column says when to call refresh_weather.

The URL asks Open-Meteo for the current temperature and weather code at one place. Change latitude and longitude to your game's location.

import { ScheduleAt, TimeDuration } from 'spacetimedb';
import { schema, table, t, type InferSchema, type ProcedureCtx } from 'spacetimedb/server';

// The current weather in Paris.
const WEATHER_URL =
  'https://api.open-meteo.com/v1/forecast?latitude=48.85&longitude=2.35&current=temperature_2m,weather_code';

// Open-Meteo updates the current weather every 15 minutes.
const REFRESH_INTERVAL_MICROS = 15n * 60n * 1_000_000n;

const weather = table(
  { name: 'weather', public: true },
  {
    id: t.u8().primaryKey(),
    temperature: t.f64(),
    weatherCode: t.u8(),
    fetchedAt: t.timestamp(),
  }
);

const weatherRefresh = table(
  { name: 'weather_refresh' },
  {
    scheduledId: t.u64().primaryKey().autoInc(),
    scheduledAt: t.scheduleAt(),
  }
);

const spacetimedb = schema({ weather, weatherRefresh });
export default spacetimedb;

type Ctx = ProcedureCtx<InferSchema<typeof spacetimedb>>;

Start the refresh​

Insert two rows into weather_refresh from the init reducer:

  • One that calls refresh_weather right away, so clients get the weather as soon as you publish. SpacetimeDB deletes it once it has run.
  • One that calls refresh_weather every 15 minutes, until the row is deleted. Open-Meteo updates the current weather every 15 minutes, so refreshing more often wouldn't get newer weather.
export const init = spacetimedb.init(ctx => {
  ctx.db.weatherRefresh.insert({
    scheduledId: 0n,
    scheduledAt: ScheduleAt.time(ctx.timestamp.microsSinceUnixEpoch),
  });
  ctx.db.weatherRefresh.insert({
    scheduledId: 0n,
    scheduledAt: ScheduleAt.interval(REFRESH_INTERVAL_MICROS),
  });
});
note

init only runs when the database is created. Publishing new code to an existing database doesn't run it again, so the refresh won't start there. To start it, either republish with --delete-data, which erases all data, or insert the rows from another reducer. Before inserting the interval row, check that weather_refresh doesn't have one already: with two of them, refresh_weather would run twice as often.

Fetch and store the weather​

Add a fetch_weather function that requests the current weather, and returns the temperature and the weather code. It's the only code specific to Open-Meteo. It gives up on the request after 10 seconds, and fails if the status isn't 200, or if the reply doesn't have the values it expects.

Then add the refresh_weather procedure. SpacetimeDB calls it with each row of weather_refresh when the row's time comes. It calls fetch_weather, then stores the result in weather, in a short transaction. If fetch_weather fails, it logs the error and returns, so weather keeps the last weather.

// Fetches the current weather. Throws if the request fails, or the reply isn't what it expects.
function fetchWeather(ctx: Ctx) {
  const response = ctx.http.fetch(WEATHER_URL, { timeout: TimeDuration.fromMillis(10_000) });
  if (response.status !== 200) {
    throw new Error(`The weather API returned status ${response.status}`);
  }
  const current = response.json().current;
  if (typeof current?.temperature_2m !== 'number' || !Number.isInteger(current?.weather_code)) {
    throw new Error('The weather API returned an unexpected reply');
  }
  return { temperature: current.temperature_2m as number, weatherCode: current.weather_code as number };
}

export const refreshWeather = spacetimedb.procedure(
  { onSchedule: weatherRefresh },
  { refresh: weatherRefresh.rowType },
  t.unit(),
  ctx => {
    let fetched: ReturnType<typeof fetchWeather>;
    try {
      fetched = fetchWeather(ctx);
    } catch (error) {
      console.error(`Could not refresh the weather: ${error}`);
      return {};
    }
    ctx.withTx(tx => {
      const row = { id: 0, ...fetched, fetchedAt: tx.timestamp };
      if (tx.db.weather.id.find(0)) {
        tx.db.weather.id.update(row);
      } else {
        tx.db.weather.insert(row);
      }
    });
    return {};
  }
);

Clients can't call refresh_weather themselves: scheduled procedures are private, so only the scheduler, the database owner and team collaborators can run them.

Show the weather on the client​

On the client, subscribe to weather, and show the weather when its row is inserted or updated. The weather code is a WMO code, which describe turns into a word.

fetched_at says when the weather was fetched. You can show it, or hide the weather when it's more than an hour old, in case the API has been failing.

import { DbConnection, tables } from './module_bindings';
import type { Weather } from './module_bindings/types';

const conn = DbConnection.builder()
  .withUri('ws://localhost:3000')
  .withDatabaseName('my-game')
  .onConnect(ctx => {
    ctx.subscriptionBuilder().subscribe([tables.weather]);
  })
  .build();

conn.db.weather.onInsert((_ctx, weather) => showWeather(weather));
conn.db.weather.onUpdate((_ctx, _old, weather) => showWeather(weather));

// A short description of a WMO weather code.
function describe(code: number) {
  if (code === 0) return 'clear';
  if (code <= 2) return 'partly cloudy';
  if (code === 3) return 'cloudy';
  if (code <= 48) return 'foggy';
  if (code <= 67) return 'rainy';
  if (code <= 77) return 'snowy';
  if (code <= 82) return 'showers';
  if (code <= 86) return 'snow showers';
  return 'stormy';
}

function showWeather(weather: Weather) {
  console.log(`${weather.temperature.toFixed(1)} °C, ${describe(weather.weatherCode)}`);
}

What's next?​

You now bring live data from an external API into your game:

  • A schedule table calls a procedure every 15 minutes, starting from init.
  • The procedure fetches the data outside of any transaction, and stores it in a public table that clients subscribe to.
  • When the API fails, the table keeps the last data, and the next refresh tries again.

To adapt it to your app:

  • APIs that need a key. Store the key in an environment variable, as in Call an AI model from your module, and send it in a header.
  • Several locations. Give weather one row per location, with its latitude and longitude. Open-Meteo accepts several comma-separated coordinates in one request, and returns a list, so one request still refreshes them all.
  • Rate limits. Check the API's limits, and refresh no more often than its data changes. Each refresh is one request, however many players are connected.
  • Refresh on demand. A reducer can't make the request, but it can insert a row into weather_refresh that runs right away. Limit how often players can do it, as the usernames guide does for name requests. In a TypeScript module, the Rate Limit submodule, a package you add to your module, can do it for you.
  • APIs that send you data. Some APIs call your server when something changes, instead of waiting for you to ask. To receive those calls, add an HTTP handler to your module.

To learn more about the features used here, see Procedures, Schedule Tables and Lifecycle Reducers.

Next, you can call an AI model from your module.