NED-GWF Web API

The NASA/IPAC Extragalactic Database (NED) is providing scrpitable access to galaxy lists and visualizations for Laser Interferometer Gravitational-Wave Observatory (LIGO)-Virgo-Kagra collaboration (LVK) 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 LVK alert. To use this service, the user will need to know the GraceID assigned by the real-time LVK 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) or csv (text/plain).
    • https://ned.ipac.caltech.edu/uri/NED::GWFglist/<fileFormat>/<GraceID>/<Pkt_Ser_Num>(/<Limit>)/
    • Since many LVK 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).
    • Note that of August 2023, ipac (text/plain) formats are no longer supported, but are still available for prior events.
  • "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).

      Table 1: List of parameters and their definitions
      Parameter Values Example Description
      GraceID ++ Required (M?S\d{6}[a-z]+|GW\d{6}) S190828j
      GW170817
      Grace Database identifier of the detection event
      Pkt_Ser_Num Required 1,2,...(or "latest") 2 VOEvent Serial number - sequence and unique
      fileFormat Required fits or csv fits format of the data stream to be returned
      Note: ipac format no longer supported as of Aug 2023

      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.

      Table 2: List of content-type and their definitions
      File Format Content-Type
      xml text/xml
      fits image/x-fits
      csv text/plain

      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 LVK pipeline to test and check end-to-end operation.

      As of August 2023, in order to reduce run-time and data volume the ipac table format for galaxy lists is no longer generated, but they are still available for prior events. Note that FITS and CSV file formats are supported for all events.

      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 LVK in the second analysis (Pkt_Ser_Num=2) of the event S200129m: https://ned.ipac.caltech.edu/uri/NED::GWFvoevent/xml/S200129m/2