NED-GWF Web API

The NASA/IPAC Extragalactic Database (NED) is providing scrpitable access to galaxy lists and visualizations for LIGO/Virgo events produced by the NED Gravitational Wave Followup (GWF) service. This service exploits the rich and constantly growing content of NED to help astronomers around the world to efficiently search for the electromagnetic (EM) counterparts to GW events. An overview of the process can be found here, and the latest event ingested by NED-GWF can be found here.

This page describes how to access: galaxy lists, an all-sky plot visualization of the galaxies, and the XML VOevent distributed in the LIGO/Virgo alert. To use this service, the user will need to know the GraceID assigned by the real-time LIGO/Virgo processing, and the event number or Packet Serial Number (See https://emfollow.docs.ligo.org/userguide/content.html for more details). Both of these can be obtained from the VOEvent notification in the XML file, querying the Grace Database, or browsing the NED-GWF contents. Services are RESTful conforming to retrieval of file- or data-based content. Currently, there are three services, and REST parameters in < > are described in the table below.

  • "GWFglist" - retrieve the list of candidate host galaxies to the associated GWF event. Return a stream of fits (image/fits), csv (text/plain), or ipac (text/plain) files.
    • https://ned.ipac.caltech.edu/uri/NED::GWFglist/<fileFormat>/<GraceID>/<Pkt_Ser_Num>(/<Limit>)/
    • Since many LIGO/Virgo events have multiple sky localization versions a shortcut for retrieving the "latest" version is provided by replacing the <Pkt_Ser_Num> with "latest" (see below for an example).
    • To support a future service that constructs lists upon request, an additional parameter is also supported <limit> to limit the length of the returned list to the 'top' (NED's definition of ranking) <limit> values. AT PRESENT, only a limit value of 20 is supported, which returns the galaxies_top20.<fileFormat>; A null or missing <limit> implies a request for "all" (i.e., the full list).
  • "GWFvoevent" - retrieve the VOEvent information packet that was processed by NED (this is a VOEvent XML stream).
    • https://ned.ipac.caltech.edu/uri/NED::GWFvoevent/xml/<GraceID>/<Pkt_Ser_Num>/
    • The "GWFvoevent" returns the XML of the VOEvent message as received by NED-GWF and is provided as a means for the user to validate/identify the event metadata to which the galaxy list applies.
  • "GWFskymap" - retrieve a visualization of the galaxies produced by the NED-GWF service overplotted onto an all-sky image of the GW localization.
    • https://ned.ipac.caltech.edu/uri/NED::GWFskymap/png/<GraceID>/<Pkt_Ser_Num>/
    • At this time the only format available is a PNG.

      • Parameters:

      Trailing virgule ('/') on URLs is desired, but not required, except when additional parameters are added to the service. Parameter values are case-sensitive (GraceIDs have capital letters, fileFormats are lower-case).

      Content-Type, MIME, Multipurpose Internet Mail Extensions:

      Streams delivered by this service are tagged with Content-Type when possible to reflect the intent. Content-Length is also provided when available.

      Content-Disposition:

      Streams may be tagged with Content-Disposition: attachment; filename=<string> (https://tools.ietf.org/html/rfc6266) where <string> is constructed using the <GraceID>, <Pkt_Ser_Num>, and file format extension as an aid to saving files when accessed interactively. Many browsers and web clients support RFC-6266 Content-Disposition with varying degrees of accuracy and success. In most intended use-cases of this program interface, the client will define the disposition, and Content-Disposition may be ignored by clients that would be using this program interface.

      Errors:

      The requested product (file or stream) is returned if found with HTTP status 200. Query errors, missing, or undefined requests return HTTP status 400 (Bad Query), 404 (Not found) or other code as appropriate.

      Caveats:

      Under normal circumstances, NED-GWF products are available within a few minutes of receiving the VOEvent. NED does not provide real-time services, so availability of GWF services and products is not guaranteed. GWF products are generated as needed, upon receipt of a VOEvent notification. NED-GWF products are not archived.

      Please note that NED processes Mock-SuperEvents (MS) to support testing of downstream users. NED does not maintain more than a few recent MS events and products online. Mock-SuperEvents are test events, not real observations, that are injected into the LIGO/Virgo pipeline to test and check end-to-end operation.

      Examples:

      Retrieve the top 20 list of galaxies in the final LALInference localization of event GW170817 sorted by 2MASS absolute K-band magnitude as a CSV output: https://ned.ipac.caltech.edu/uri/NED::GWFglist/csv/GW170817/3/20 - Note: we only provide the NED-GWF products for the final LALInference localization.

      Retrieve the full list of galaxies in the second analysis (Pkt_Ser_Num=2) of the event S200129m as a FITS output: https://ned.ipac.caltech.edu/uri/NED::GWFglist/fits/S200129m/2

      Retrieve the sky map visualization of galaxies in the second analysis (Pkt_Ser_Num=2) of the event S200129m as a png output: https://ned.ipac.caltech.edu/uri/NED::GWFskymap/png/S200129m/2

      Retrieve the VOevent XML file distributed by LIGO/Virgo in the second analysis (Pkt_Ser_Num=2) of the event S200129m: https://ned.ipac.caltech.edu/uri/NED::GWFvoevent/xml/S200129m/2