Endpoints

The apiv1 endpoints are listed below.

Most endpoints return a JSON-encoded dictionary; the ‘Result’ values documented below refer to the contents of the result entry in the JSON-dict. See Returned content for details.

Query endpoints

GET /apiv1/list/ivorn_ncites

(Link)

Result (list of 2-element lists):
[[ivorn, n_cited], ...]

Get rows containing citation counts. Row entries are:

  • IVORN of packet
  • Number of times this packet is cited by others
GET /apiv1/list/ivorn_nrefs

(Link)

Result (list of 2-element lists):
[[ivorn, n_refs], ...]

Get rows containing reference counts. Row entries are

  • IVORN of packet
  • Number of references to other packets, in this packet.
GET /apiv1/list/ivorn

(Link)

Result (list of strings):
[ ivorn1, ivorn2, ... ]

List of ivorns matching querystring. Number returned is limited by the limit parameter, which defaults to 100 (see List-pagination controls).

GET /apiv1/map/authored_month_count

(Link)

Result:
Dict: Mapping month -> packet counts per-month.

Here, ‘month’ refers to the month of the ‘authoring’ DateTime, i.e. the Who.Date element of the VOEvent. NB, may be None.

GET /apiv1/map/stream_role_count

(Link)

Result:
Nested dict: Mapping stream -> role -> packet counts per-stream-and-role.
GET /apiv1/map/stream_count

(Link)

Result:
Dict: Mapping stream -> packet counts per-stream.
GET /apiv1/map/role_count

(Link)

Result:
Dict: Mapping role -> packet counts per-role.
GET /apiv1/count

(Link)

Result (int):
Number of packets matching querystring.

Returns total number of packets in database if the querystring is blank.

GET /apiv1/

(Link)

API root url. Shows a list of active endpoints.

Single-packet endpoints

Unlike the query-endpoints, these return data on a single packet.

The IVORN of the desired packet should be appended to the endpoint-URL in URL-encoded form.

GET /apiv1/packet/synopsis/(path: url_encoded_ivorn)
GET /apiv1/packet/synopsis/

(Link)

Result:

Nested dict providing key details, e.g.:

{"coords": [
                {
                    "dec": 10.9712,
                    "error": 0.05,
                    "ra": 233.7307,
                    "time": "2015-10-01T15:04:22.930000+00:00"
                },
                ...
            ],
 "refs":   [
                {
                    "cite_type": u"followup",
                    "description": "This is the XRT Position ...",
                    "ref_ivorn": "ivo://nasa.gsfc.gcn/SWIFT#BAT_..."
                },
                ...
            ],
 "voevent": {
                "author_datetime": "2015-10-01T15:04:46+00:00",
                "author_ivorn": "ivo://nasa.gsfc.tan/gcn",
                "ivorn": "ivo://nasa.gsfc.gcn/SWIFT#BAT_GRB_Pos_657286-112",
                "received": "2015-11-19T20:41:38.226431+00:00",
                "role": "observation",
                "stream": "nasa.gsfc.gcn/SWIFT",
                "version": "2.0"
            }
 "relevant_urls": [ "http://address1.foo.bar",
                    "http://address2.foo.bar"
                    ]
}

Returns some key details for the packet specified by IVORN.

The required IVORN should be appended to the URL after /synopsis/ in URL-encoded form.

GET /apiv1/packet/xml/(path: url_encoded_ivorn)
GET /apiv1/packet/xml/

(Link)

Returns the XML packet contents stored for a given IVORN.

The required IVORN should be appended to the URL after /xml/ in URL-encoded form.