API Reference

Note that all the functions in voeventdb.remote mirror the underlying server functionality. The server docs may be helpful when trying to understand the underlying data-queries and filters.

Package default variables

Define some package-level default values:

voeventdb.remote.default_host = 'http://voeventdb.4pisky.org'

The default host to query.

voeventdb.remote.default_list_n_max = 5000

Maximum number of rows to fetch from a list request, by default.

If you really want to fetch more rows in a single query, this can be changed for a single request by setting the n_max parameter-value. Setting a value of n_max=0 will fetch all available rows.

voeventdb.remote.default_pagesize = 1000

Number of rows fetched in each HTTP GET request (when querying list-endpoints).

When many rows are available, the top-level interface will make multiple GET requests behind the scenes, fetching pagesize rows in each GET. This variable can typically be left unchanged for casual usage - it’s aimed at advanced usage when trying to improve network performance.

API version 1 (apiv1)


Functions representing endpoints

Endpoint definitions can be found in the server-docs. Function calls use a consistent style throughout:

  • For all endpoints you can specify a particular host. If this is None, the default host will be used.
  • All endpoint-functions can be passed filters, a dictionary defining a set of filter-keys and values (except for the packet_ functions, which retrieve details on a single packet as specified by the IVORN).
  • List endpoints can be passed an order (see OrderValues), and an n_max parameter which limits the number of list-items returned. There is also a pagesize parameter, but this can typically be left at the default setting (see voeventdb.remote.default_pagesize).


These are imported into the apiv1 namespace for brevity, so you can access them like voeventdb.remote.apiv1.count().

voeventdb.remote.apiv1.endpoints.count(filters=None, host=None)[source]
voeventdb.remote.apiv1.endpoints.list_ivorn(filters=None, order=None, pagesize=None, n_max=None, host=None)[source]
voeventdb.remote.apiv1.endpoints.list_ivorn_ncites(filters=None, order=None, pagesize=None, n_max=None, host=None)[source]
voeventdb.remote.apiv1.endpoints.list_ivorn_nrefs(filters=None, order=None, pagesize=None, n_max=None, host=None)[source]
voeventdb.remote.apiv1.endpoints.map_authored_month_count(filters=None, host=None)[source]
voeventdb.remote.apiv1.endpoints.map_role_count(filters=None, host=None)[source]
voeventdb.remote.apiv1.endpoints.map_stream_count(filters=None, host=None)[source]
voeventdb.remote.apiv1.endpoints.map_stream_role_count(filters=None, host=None)[source]
voeventdb.remote.apiv1.endpoints.packet_synopsis(ivorn, host=None)[source]
voeventdb.remote.apiv1.endpoints.packet_xml(ivorn, host=None)[source]

Enumeration classes

class voeventdb.remote.apiv1.FilterKeys[source]

Enumerates valid filters.

Useful for building dictionaries representing filter-sets, eg.:

filters = {
    FilterKeys.ivorn_contains: 'GRB',
    FilterKeys.role : 'observation',

For definitions of the various filters, and examples of valid values, see the voeventdb query-filters page.

authored_since = 'authored_since'
authored_until = 'authored_until'
cited = 'cited'
cone = 'cone'
coord = 'coord'
dec_greater_than = 'dec_gt'
dec_less_than = 'dec_lt'
ivorn_contains = 'ivorn_contains'
ivorn_prefix = 'ivorn_prefix'
ref_any = 'ref_any'
ref_contains = 'ref_contains'
ref_exact = 'ref_exact'
role = 'role'
stream = 'stream'
class voeventdb.remote.apiv1.OrderValues[source]

Enumerates valid orderings.

For details see this section in the voeventdb.server docs.

author_datetime = 'author_datetime'
author_datetime_desc = '-author_datetime'
id = 'id'
id_desc = '-id'
ivorn = 'ivorn'
ivorn_desc = '-ivorn'

Helper classes

Helper classes for providing convenience parsing of returned JSON content.

class voeventdb.remote.helpers.SkyEvent(skyevent_dict)[source]

Represents universal attributes of an observed event on sky.

I.e. the most basic details that we expect to find in all packets reporting events with sky-positions.


astropy.coordinates.SkyCoord – Best-estimate sky-coordinates of the event being reported.

position error

astropy.coordinates.Angle – Error-cone on the position estimate.

timestamp of event

datetime.datetime – Timestamp for the reported event (UTC timezone).

class voeventdb.remote.helpers.Synopsis(synopsis_dict, api_version_string='apiv1')[source]

Parses the output from the ‘synopsis’ endpoint into a class-object.


datetime.datetime – The Who.Date timestamp. (Parsed to datetime, UTC timezone). May be None if no timestamp present in the VOEvent packet.


string – The Who.AuthorIVORN entry. May be None if no entry present in the VOEvent packet.




datetime.datetime – Dates exactly when the packet was loaded into this instance of voeventdb.








list – A list of SkyEvent objects. These are parsed from the WhereWhen section of a VOEvent packet, if possible. (If the packet has no WhereWhen data, this is an empty list).


listastropy.coordinates.SkyCoord positions. This is a syntax-shortcut, the positions are just those of the sky_events entries, if any are present.


list – References to other VOEvent packets. This is a list of dictionaries representing any references present in the Citations section of the VOEvent packet.

Additional convenience functions

Convenience functions for exploring / extracting more complex data-structures.

voeventdb.remote.apiv1.convenience.citation_network_map(ivorn, max_recursion_levels=5)[source]