Querying the REST API

The voeventdb web-interface is designed around widely used RESTful concepts, which means (simplifying grossly) that all the details of your data query are encoded in an HTTP URL. By making requests at that URL, you get back the data matching your query. You can try this out by following links and editing the URL in your browser, but typically you’ll want to grab data using a scripting library such as Python’s requests. [1]

[1]	A ready-made Python-client library which wraps requests in a convenient fashion can be found at https://github.com/timstaley/voeventdb.remote.

Finding and using endpoints

The base URLs which represent different queries are known as endpoints - full listings for voeventdb can be found on the Endpoints page. Some useful places to start are the root endpoint, which provides a concise listing of the endpoints available, and the stream count endpoint, which serves as a sort of ‘contents’ page for the database.

Narrowing your query

By default, most endpoints return data on all VOEvents currently stored in the database. [2] To narrow down your query to a specific subset of the VOEvents, you can apply a selection of the available filters listed on the Query filters page. Filters are applied by adding key-value pairs as part of the query-string in your HTTP request.

For example, to return a count of the packets stored since the start of November 2015, which have been assigned the ‘observation’ role, you can form an HTTP address like:

http://voeventdb.4pisky.org/apiv1/count?authored_since=2015-11&role=observation

Though typically you would let your scripting library do the job of stitching together the various parts. See the Query filters page for more details.

Note

You can apply any filter (or combination of filters) to any endpoint, so (for example)

http://voeventdb.4pisky.org/apiv1/map/stream_count?authored_since=2015-11&role=observation

is also a valid query-URL (where we have replaced the /apiv1/count endpoint with /apiv1/map/stream_count).

[2]	The exceptions are the single-packet endpoints:, which are intended to retrieve data pertaining to a single VOEvent.

URL-Encoding

Note that if you are accessing the single-packet endpoints:, or specifying a query-filter value which contains the # character, then you will need to use URL-encoding (because otherwise the query-value is indistinguishable from an incorrectly-formed URL). It’s simple to URL-encode the value using a web-based tool, or e.g. in Python:

import urllib
s = urllib.quote_plus("ivo://foo.bar/baz#quux")
print(s)

List-pagination controls

The database can easily handle millions of entries, so it makes sense to break up the return-data for queries which return lists of data. You can use pagination-keys in the same manner as query-keys (i.e. in the query-string) to control this:

class voeventdb.server.restapi.v1.definitions.PaginationKeys

These query-keys control the ordering and subset (‘page’) of results.

Use limit and offset values in your querystring to control slicing, i.e. the subset of an ordered list returned in the current query.

(Only applies to list views, e.g. the IVORN listing endpoint.)

The keywords are adopted from SQL, cf http://www.postgresql.org/docs/9.3/static/queries-limit.html

Note that if no values are supplied, a default limit value is applied. (You can still check what it was, by inspecting the relevant value in the result-dict.)

limit = 'limit'

The maximum number of results returned for a single request.

offset = 'offset'

The number of rows ‘skipped’ before returning results for a request.

order = 'order'

Controls the ordering of results, before limit and offset are applied. Valid values are enumerated by the OrderValues class.

class voeventdb.server.restapi.v1.definitions.OrderValues

Values that may be used in a querystring with the ‘order’ key.

E.g. By specifying order=author_datetime in a querystring, results are returned ordered by author_datetime (ascending, i.e. oldest first). By default, results are returned in database-id (ascending) order, which in effect means that the first results to be loaded into the database are returned first.

Each value has a pairing with a ‘-‘ prefix, implying reverse (descending) ordering.

author_datetime = 'author_datetime'

author_datetime_desc = '-author_datetime'

Order results by author_datetime (timestamp from the Who section). Default (‘ascending’) implies oldest-first.

id = 'id'

id_desc = '-id'

Order results by database-id (assigned as events are added to the database). This is the default setting.

ivorn = 'ivorn'

ivorn_desc = '-ivorn'

Order results by ivorn (alphabetically).

Returned content

class voeventdb.server.restapi.v1.viewbase.ResultKeys

Most endpoints return a JSON-encoded dictionary. [3]

At the top level, the dictionary will contain some or all of the following keys:

[3]	(The exception is the XML-retrieval endpoint, obviously.)

Note

The key-strings can be imported and used in autocomplete-friendly fashion, for example:

from voeventdb.server.restapi.v1 import ResultKeys as rkeys
print rkeys.querystring

endpoint = 'endpoint'

The endpoint the query was made against.

limit = 'limit'

The maximum number of entries returned in a single request (Only applies to list-view endpoints.)

querystring = 'querystring'

A dictionary displaying the query-string values applied. (With urlencode-decoding applied as necessary.)

Note that each entry contains a list, as a query-key may be applied multiple times.

result = 'result'

The data returned by your query, either in dictionary or list format according to the endpoint.

See endpoint listings for detail.

url = 'url'

The complete URL the query was made against.