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 ofn_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 isNone
, thedefault host
will be used. - All endpoint-functions can be passed
filters
, a dictionary defining a set offilter-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
(seeOrderValues
), and ann_max
parameter which limits the number of list-items returned. There is also apagesize
parameter, but this can typically be left at the default setting (seevoeventdb.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.
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]¶
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.
-
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'¶
-
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.
-
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')[source]¶ Parses the output from the ‘synopsis’ endpoint into a class-object.
datetime.datetime
– TheWho.Date
timestamp. (Parsed to datetime, UTC timezone). May beNone
if no timestamp present in the VOEvent packet.
string – The
Who.AuthorIVORN
entry. May be None if no entry present in the VOEvent packet.
-
ivorn
¶ string
-
received
¶ datetime.datetime
– Dates exactly when the packet was loaded into this instance of voeventdb.
-
role
¶ string
-
stream
¶ string
-
version
¶ string
-
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 thesky_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.