Skip to content

App Request Builder

The Request Builder is where you put a subscription together on a map and get a ready-to-run Python snippet for it. You choose the geo areas, the event types and the lens. The builder then writes the subscribe call your application runs. Opening the page needs subscriptions:write.

The builder is an interactive map, so it needs a desktop-sized window. On a narrower screen the page shows Needs a larger screen instead.

The portal writes the request; your application makes it

The builder never creates a subscription itself. The subscription exists once your application runs the snippet, and it belongs to the app client whose credentials the snippet uses. That app client's dialog lists it and lets you delete it: see App Clients.

What you choose

A subscription has three parts, and the builder needs all three (see Subscriptions & Events):

  1. Geo areas: where you care about. One or more geohash cells.
  2. Event types: what you care about.
  3. Lens: how sensor data becomes events.

If you choose Get Python snippet while one is missing, that section is marked At least one required (geo areas, event types) or Required (lens).

Switching to another organization clears every choice on the page.

Geo areas

  • Click a tile to drill in. With nothing selected, the grid is one-character cells. Each click selects a tile and draws a grid one character finer inside it, down to nine characters. Clicking outside the selected tile goes back up a level. The Precision line above the field shows the current grid.
  • Or type a code. The selected tile's code appears in the Geohash field. You can also type a code there, and the map moves to it.
  • Add it with ✓, or press Enter. It joins Selected geohashes. Each entry can be shown on the map, copied or removed.

The builder offers cells only. To subscribe to everywhere you can see, replace the regions in the copied snippet with ["*"] on its own.

The builder doesn't check the platform's bounds. Nested cells collapse into the coarser one, and a request is refused if it has more than 64 cells or would match more than 200 sensors. Those checks happen when the snippet runs: see Where (geographic regions).

Sensors on the map

  • The pins are your organization's own active sensors, coloured by sensor type. The shaded shape around a pin is that sensor's area of view, the ground it observes. Subscriptions match sensors by that area, not by where the pin stands.
  • Sensors on map lists the sensor types present. Click a type to hide or show its pins. If the sensors can't be loaded, the section shows the error with Retry.
  • Hover a pin to see its name. Click it to open the sensor dialog, the same one the Sensors page opens. You can edit or decommission the sensor there only if your role allows it: see The sensor dialog.
  • Sensors in selection lists, by name, the sensors whose area of view overlaps one of your selected geo areas. Hidden sensor types are left out. A sensor with no area of view is listed when its location lies inside a selected area. Each entry opens the same sensor dialog, so this list is also the keyboard route to sensor details.

A subscription can match more than the map shows

The map shows only your own organization's sensors. When the snippet runs, the platform also matches other organizations' public sensors whose area of view overlaps your geo areas. The subscription's coverage report has the platform's own count.

Event types

Choose Add event type… and search. The picker searches the server as you type, across every organization's event types (see Sensors & Tags). Each type you pick becomes a removable chip. The snippet passes each type's slug. When the slug differs from the name, hover the chip to see it.

Lens

Choose Choose a lens… to open the lens picker. A subscription names exactly one lens, by its alias.

  • With lenses:read, the picker lists your organization's lenses by name and alias, and you can search them.
  • Anyone can type an alias. When what you type is a valid alias that isn't already in the list, the picker offers Use alias …. It can be your own organization's lens or another organization's public one. Typing is the only way to name another organization's public lens, because no list shows those. It is also how members without lenses:read choose a lens. The built-in Application Builder role doesn't grant lenses:read: see Subscription permissions.
  • A typed alias isn't checked yet. The chosen lens reads Checked when the subscription is created. An alias that doesn't exist and another organization's private lens are refused the same way when the snippet runs.
  • If your organization's lenses can't be loaded, the error shows with Retry, and typing an alias still works.

Getting the snippet

  1. Choose Get Python snippet at the bottom right of the page.
  2. Pick the App client the snippet should authenticate as. Listing app clients needs app_clients:read. If your organization has none yet, the dialog says so, and members who can create app clients get a Create one button.
  3. Fill in the client secret. The app client list never carries secrets:
    • With app_clients:write, choose Show client secret. The snippet is rebuilt with the secret, which stays masked on screen and is included when you copy.
    • Without it, the snippet carries a <your client secret> placeholder for you to replace.
  4. Copy the snippet. If it contains the secret, treat it like a password.

The core of the snippet looks like this:

from dory import DoryClient

client = DoryClient(
    client_id="...",                  # the app client you picked
    client_secret="<your client secret>",
)


def handle_event(event):
    print(f"Received: {event}")


subscription_id = client.rabbitmq.subscribe(
    event_types=["..."],       # the slugs of the event types you picked
    geohash_regions=["..."],   # your selected geohashes
    lens_alias="...",          # the lens you chose
    callback=handle_event,
)

After subscribing, it prints the subscription ID and listens for events. On Ctrl+C, or when the process is told to stop, it deletes the subscription and closes the client.

To run it, install the Application SDK first. The SDK isn't on PyPI, so follow Getting Started: Install.

Ignore the install hint in the snippet dialog

The one-line install command under the snippet is out of date. Installing by package name won't find the SDK. Use the steps linked above.

What happens when the snippet runs

  • subscribe() returns the subscription ID straight away. The platform accepted the request, its status is pending, and its delivery queue exists. The SDK starts listening on that queue at once.
  • Setup continues in the background. The platform matches every eligible sensor whose area of view overlaps your geo areas. It picks the templates in your lens that produce your event types, and starts or reuses processors. Events start arriving once that is done. See From subscription to delivered stream.
  • A refused request raises an error. Causes include an event type the platform doesn't know, a lens you can't use, or a request over one of the bounds above. None of these creates a subscription. See If something goes wrong.
  • Nothing matching isn't an error. The subscription still becomes active, and its coverage report says, for each event type, why nothing produces it yet. The snippet doesn't print that report. Add client.rabbitmq.wait_until_ready(subscription_id) after subscribe() to get it: see Wait for provisioning.
  • The match is kept current. Every hour the platform matches the subscription again as sensors, lenses and templates change. See The hourly re-check.
  • The subscription outlives the script. If the process is killed before it deletes the subscription, the subscription stays. Delete it from the app client's dialog in the portal, or from any program using the same credentials.

Tips

  • If no events arrive, read the coverage report before widening the area. Regions choose which sensors serve you, not which events are delivered. An uncovered event type may have no sensor in range, or no template in the lens that produces it. See The coverage report.
  • Check Sensors in selection before you copy. It shows which of your own sensors your areas reach. Other organizations' public sensors come on top when the snippet runs.
  • Wider areas reach more sensors, up to a limit. Shorter codes cover more ground, but a request that would match more than 200 sensors is refused.