astrocolibri is the official Python SDK for Astro-COLIBRI. It has two parts:

• Client queries the Astro-COLIBRI API. It looks up events and sources, and searches for transients within a time window or around a position on the sky. Searches need your Astro-COLIBRI user ID.
• Consumer receives alerts from the Astro-COLIBRI alert broker in real time. It needs broker credentials.

Requires Python 3.9+. This also installs requests and confluent-kafka. The latter needs the librdkafka C library, which the wheel bundles on most platforms; if you hit a build error, install librdkafka with your system package manager first (e.g. apt install librdkafka-dev or brew install librdkafka).

Alternatively, install the latest version directly from the GitHub repository:

Querying the API

Open astro-colibri.com/account (the link asks you to sign in if needed) and copy your user ID. It identifies your account to the API, which uses it for the per-account search quota and for anything specific to you, such as your watchlist. Treat it like a personal key: keep it out of shared notebooks and published code.

Make it available to the SDK in one of two ways. Export it once in your shell or deployment environment:

or pass it explicitly, for example from a variable your script already holds. The explicit argument wins over the environment variable:

Then search:

Event and source lookups work without a user ID; searches need one and count against your daily quota. The SDK keeps the user ID in memory only: it writes no configuration file, and leaves the ID out of repr() and every error message.

Listening to the broker

Get your credentials at astro-colibri.com/broker (the link takes you straight there and asks you to sign in if needed). Then create a Consumer with them, subscribe to one or more topics, and iterate over incoming alerts:

That loop is the whole listener: consume() never ends on its own, so the script keeps waiting for the next alert instead of exiting once it has caught up. Stop it with Ctrl-C.

Payloads arrive decoded: alert.value() is a dict on the .JSON topics and the XML document as a str on the .VOEvent topics — never raw bytes. See the Alert reference for everything an alert carries.

The client connects to the official broker and starts from the earliest alert still inside the retention window. Your read position is remembered across restarts, so you resume exactly where you left off. If you run several scripts on the same credentials, give each one its own group_id (see Consumer() below).

1. Setup and a first search

latest_transients.py lists the transients of a time window. Install the SDK, configure your user ID as in the quick start, download the script and run it with an explicit window in UTC:

Without arguments it searches the previous full day in UTC. Its core is a single call:

results is the API's JSON as a dict. Its "voevents" list holds one dict per transient. The table shows the fields most scripts need; the API documentation lists every event parameter.

Every field the API returns is kept, including fields added in later API versions.

If it does not work

• "latest_transients() needs your Astro-COLIBRI user ID": no user ID is configured. Export ASTROCOLIBRI_UID in the shell that runs the script, or pass uid=.
• "User does not exist": a user ID is configured but wrong. Copy it again from your account page rather than retyping it.
• "Rate limit exceeded": the daily quota is used up, and AstrocolibriRateLimitError.reset_time says when it renews. An identical search repeated within the same half hour is normally answered from the API's cache without counting again.
• "start has no timezone": append Z or an offset such as +00:00 to the time.
• An empty "voevents" list is a valid answer: nothing matched. Widen the window, or check the filter if you passed one.

2. Looking up events

Lookups are free: they need no user ID and do not count against your quota. get_event.py fetches one event by trigger ID or name:

A name can belong to several events. GRB 190829A was localized by both Fermi/GBM and Swift/XRT, and a lookup by name returns only one of them, not necessarily the best. resolve_source.py lists every localization, best first, then fetches the best one in full:

In your own code, the same two steps are:

Each summary carries trigger_id, ra, dec, err and timestamp, plus observatory and instrument when known. Note that timestamp is in milliseconds since the Unix epoch.

When nothing is found

• get_event() raises AstrocolibriNotFoundError. Spacing does not matter ("GRB190829A" finds "GRB 190829A"), but spelling does.
• resolve_source() returns an empty list for catalog sources (TeVCat, 4FGL, X-ray binaries), bright stars and objects known only to SIMBAD. get_source_summary() covers those, and returns None only for a name no catalog knows. A SIMBAD lookup can be slow: pass timeout=300.
• get_events([...], missing="skip") looks up several identifiers in one request and leaves out the ones that match nothing.

3. Searching around a position

cone_search.py searches a 2° cone around the Crab Nebula over the last 30 days. Each run is one search against your quota.

Angles are decimal degrees or sexagesimal strings, and the unit is read from the notation, never from the size of the number. These three calls search the same position:

A malformed or out-of-range angle raises AstrocolibriConfigError before anything is sent, so it costs no quota. Right ascension must lie within [0, 360), declination within [-90, 90] and the radius within (0, 180]. Hours are accepted for right ascension only, and a bare "30m" right ascension is refused as ambiguous: minutes of time, or of arc?

The time window applies to transients only. The catalog groups of the result, "sources", "Xsources" and "icecat", list every known source in the cone whatever its date.

Searching a localization region. Gravitational waves, Fermi/GBM and IPN bursts, IceCube neutrinos and MAXI transients are localized to regions far from circular. contour_search.py searches inside the 90% localization contour of the gravitational-wave event S230518h, widened by 1°, for the week after the merger:

If no contour is stored for the event, the API searches the circle instead. That is not an error, so check "search_region" to know which area was searched.

4. Filters and results

Without a filter, a search returns every event your account may access. The SDK sends that choice explicitly, as a match-everything filter, which also lets the API answer a repeated search from its cache.

An API filter dictionary. Filters are the JSON structure the Astro-COLIBRI app builds. The filter notebook walks through that structure interactively, and the photometry sub-filter notebook shows how to select fast-rising or fast-fading transients from their light curves. Pass a filter as event_filter, here to keep optical transients only:

Conditions combine with AndSpecification and OrSpecification. Optical transients brighter than magnitude 18:

An invalid filter comes back as AstrocolibriAPIError, with the API's explanation in its message. An empty dictionary is refused before sending: the API would read it as "no filter" and apply your saved filters instead.

Your saved app filters. use_saved_filters=True applies the latest filters saved in the Astro-COLIBRI app for your account. The API fails if none were ever saved. Such a search is never answered from the cache, so every call counts against your quota, and it cannot be combined with event_filter.

What comes back. Both searches return the API's JSON as a dict of result groups:

With include_watchlist=True, a cone search merges the watchlist events that lie inside the cone into "voevents" instead. Unknown keys and fields are passed through unchanged, so responses from newer API versions keep working.

Client wraps the public Astro-COLIBRI API at https://astro-colibri.science. Results are the API's own JSON as plain Python objects. The client only reads, and it never retries a request on its own: a search can consume quota or start expensive processing on the server, so repeating one is your decision. Every method accepts timeout= in seconds, overriding the client's default for that call. The underlying HTTP endpoints are documented on the API documentation page.

Consumer receives alerts from the Astro-COLIBRI alert broker. The broker page documents what the stream carries: the available topics, what reaches the important stream, retention and delivery, and the connection parameters for clients other than this SDK.

Kafka carries bytes, but you don't have to handle them. Every alert yielded by consume() is an Alert, whose value() is the payload already decoded:

Everything else about the record stays available:

A payload that cannot be decoded raises AstrocolibriDecodeError — and only when you read it, so one malformed record never takes down a listener that has been running for weeks:

All exceptions raised by astrocolibri derive from a single base class, so you can catch any client error with one except:

Please acknowledge the use of the software and cite the Astro-COLIBRI platform papers:

• Reichherzer et al. (2021), Astro-COLIBRI — The COincidence LIBrary for Real-time Inquiry for Multimessenger Astrophysics, ApJS 256, 5, doi:10.3847/1538-4365/ac1517.
• Reichherzer et al. (2023), Astro-COLIBRI 2 — An Advanced Platform for Real-Time Multi-Messenger Discoveries, Galaxies 11, 22, doi:10.3390/galaxies11010022.

This source-available software is licensed under the PolyForm Noncommercial License 1.0.0. It may be used, modified, and redistributed for permitted noncommercial purposes, including use by educational institutions and public research organizations.

Commercial use requires a separate written license. Contact Astro-COLIBRI (Fabian Schüssler).

Use of Astro-COLIBRI hosted services, including the Kafka broker, the API and their data, is governed separately by the Astro-COLIBRI Terms of Service.