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. 
|||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.  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:
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.
You can apply any filter (or combination of filters) to any endpoint, so (for example)
is also a valid query-URL (where we have replaced the
|||The exceptions are the single-packet endpoints:, which are intended to retrieve data pertaining to a single VOEvent.|
Note that if you are accessing the
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
import urllib s = urllib.quote_plus("ivo://foo.bar/baz#quux") print(s)
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:
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.)
The maximum number of results returned for a single request.
The number of rows ‘skipped’ before returning results for a request.
Values that may be used in a querystring with the ‘order’ key.
E.g. By specifying
order=author_datetimein 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.
Order results by author_datetime (timestamp from the Who section). Default (‘ascending’) implies oldest-first.
Order results by database-id (assigned as events are added to the database). This is the default setting.
Order results by ivorn (alphabetically).
At the top level, the dictionary will contain some or all of the following keys:
 (The exception is the XML-retrieval endpoint, obviously.)
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
The endpoint the query was made against.
The maximum number of entries returned in a single request (Only applies to list-view endpoints.)
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.
The data returned by your query, either in dictionary or list format according to the endpoint.
See endpoint listings for detail.
The complete URL the query was made against.