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)

Endpoints

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).

Note

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)

voeventdb.remote.apiv1.endpoints.list_ivorn(filters=None, order=None, pagesize=None, n_max=None, host=None)

voeventdb.remote.apiv1.endpoints.list_ivorn_ncites(filters=None, order=None, pagesize=None, n_max=None, host=None)

voeventdb.remote.apiv1.endpoints.list_ivorn_nrefs(filters=None, order=None, pagesize=None, n_max=None, host=None)

voeventdb.remote.apiv1.endpoints.map_authored_month_count(filters=None, host=None)

voeventdb.remote.apiv1.endpoints.map_role_count(filters=None, host=None)

voeventdb.remote.apiv1.endpoints.map_stream_count(filters=None, host=None)

voeventdb.remote.apiv1.endpoints.map_stream_role_count(filters=None, host=None)

voeventdb.remote.apiv1.endpoints.packet_synopsis(ivorn, host=None)

voeventdb.remote.apiv1.endpoints.packet_xml(ivorn, host=None)

Enumeration classes

class voeventdb.remote.apiv1.FilterKeys

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

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)

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.

position

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')

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

author_datetime

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

author_ivorn

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

ivorn

str

received

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

role

str

stream

str

version

str

sky_events

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).

coords

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

references

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)