Primary Methods¶
There are two primary methods for submitting API queries. The first is query_object which can be used to search the OAC based on an event name. Multiple events can be retrieved by submitting a list of event names.
The default behavior returns a top-level list of all available metadata for the queried event(s).
>>> from astroquery.oac import OAC
>>> metadata = OAC.query_object("GW170817")
The query can be further refined by using the available QUANTITY and ATTRIBUTE options. For example, to retrieve the light curve for an object:
>>> photometry = OAC.query_object("GW170817", quantity="photometry",
... attribute=["time", "magnitude",
... "e_magnitude", "band",
... "instrument"])
The results of a query can be further refined by using the ARGUMENT option
>>> photometry = OAC.query_object("GW170817", quantity="photometry",
... attribute=["time", "magnitude",
... "e_magnitude", "band",
... "instrument"],
... argument=["band=i"])
The second method available is query_region which performs a cone or box search for a given set of coordinates. Coordinates can be submitted as an Astropy SkyCoord object or a list with [ra, dec] structure. Coordinates can be given in decimal degrees or sexigesimal units. The API can currently only query a single set of coordinates.
For this example, we first establish coordinates and search parameters:
>>> import astropy.coordinates as coord
>>> import astropy.units as u
>>> from astroquery.oac import OAC
>>> #Sample coordinates. We are using GW170817.
>>> ra = 197.45037
>>> dec = -23.38148
>>> test_coords = coord.SkyCoord(ra=ra, dec=dec, unit=(u.deg, u.deg))
>>> test_radius = 10*u.arcsec
>>> test_height = 10*u.arcsec
>>> test_width = 10*u.arcsec
An example cone search:
>>> photometry = OAC.query_region(coordinates=test_coords, radius=test_radius,
... quantity="photometry",
... attribute=["time", "magnitude",
... "e_magnitude", "band", "instrument"])
An example box search:
>>> photometry = OAC.query_region(coordinates=test_coords,
... width=test_width, height=test_height,
... quantity="photometry",
... attribute=["time", "magnitude",
... "e_magnitude", "band", "instrument"])
As with the query_object method, searches using query_region can be refined using the QUANTITY, ATTRIBUTE, and ARGUMENT options. The complete list of available options can be found at the OAC API Github Repository
The default behavior for both methods is to return an Astropy table object. Queries can also be returned as a JSON compliant dictionary using the data_format option.