The KOA Program-Friendly Image Access Service

 

Overview of the KOA Program Interface for Images

KOA provides a program interface for use on the command line or within a script that discovers public imaging data acquired by those Keck instruments equipped with an imaging mode. It offers a common interface for accessing images acquired by all Keck instruments: users thus need learn only one interface specification for all KOA holdings. The interface specification ("Application Program Interface (API) ") complies with Version 2 (2015-06-10) of the Simple Image Access protocol (SIA) defined by the International Virtual Observatory Alliance (IVOA)

Users need not know the details of the protocol to use the interface, which constructs a URL that submits a query to KOA and returns a list of images in an ASCII format; this list can be parsed by a program or script. Briefly, the KOA API discovers images for a specified instrument by performing a cone or box search on the sky, and returns lists of images whose footprints on the sky intersect the area of the cone or box, with the lists filtered according to user-specified criteria of, e.g. time-range. The API assumes that the image footprint on the sky is represented in the World Coordinate System (WCS). Generally, the raw data files generated at the time of observation do not contain WCS keywords, and therefore KOA has estimated them on a per instrument basis, based on knowledge of the pointing of the telescope and the instrument's orientation and configuration. We urge users to familiarize themselves with the consequences of this approach, described below.

 

KOA Images and the World Coordinate System (WCS)

Spatial matching between the search region and the sky coverage of the KOA images requires that we specify the footprint of each image on the sky. For nearly all observations of three instruments—NIRC2, MOSFIRE, and OSIRIS— the image footprint is represented as World Coordinate System (WCS) keywords in the FITS headers. For these observations, the spatial search is exact for cone and polygon searches.

For the remaining instruments, the image footprints are not recorded in the FITS headers (see Availability and Creation of Sky Coordinates for more information.) We therefore assume the image is centered on the position on the sky where the telescope was pointing. We convert polygon searches to cone searches by enclosing the requested search area in a circular region. For both cone and polygon searches, we then use the instrument field-of-view to extend the circular region on the sky, as shown in the diagrams below for a cone search (top figure) and for a polygon search (bottom figure):

spatial searches cone

spatial searches polygon

This technique in effect pads the search areas a few arcseconds, and there is a small probability that the service returns additional records over and above what would be expected from an exact search. We recommend users use the search results with this possibility in mind.

 

Running a Program-Friendly Query

Program-friendly queries are made on a per instrument basis: please note that queries across multiple instruments are not supported in a single call to the service.

We recommend new users take advantage of the query builder form. It is intended as starting point for building program-friendly queries and not as a new web interface to KOA. If you do wish to perform web-based searches for KOA data, please use the web interface at https://koa.ipac.caltech.edu. On the query builder page, start by selecting an instrument from the drop-down list to populate the fields with parameter values for that instrument. Click Submit to return the query URL, a list of keyword/value pairs corresponding to the query, a table of records for up the first ten images discovered, and a key to the columns in the output table. You can of course modify the query with your own parameters. You may also build a query from scratch, or edit the examples provided below.

The program-friendly interface call will generally be run on the command line, or embedded in a script or program. The easiest way to automate these calls is to take advantage of wget and cURL, free tools for downloading content from web servers. Many Linux distributions pre-install these tools, but Mac OS X and Windows users will generally need to install them. For help in downloading, installing and using wget, visit the IRSA batch download help page.To download cURL, visit http://curl.haxx.se/.

Usage is straightforward. To download the results from this example query:

https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS

invoke wget as follows:

wget -O deimos.vot 'https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS'

and it will download the results into the file deimos.vot.

cURL doesn't like spaces in the URL, so we need to replace them with something that is equivalent (either "+" or "%20"). The following two cURL examples provide the same records.

curl -o deimos.vot 'https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE%20150.0%2045.0%205.0&INSTRUMENT=DEIMOS'

curl -o deimos.vot 'https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE+150.0+45.0+5.0&INSTRUMENT=DEIMOS'

 

Program-Friendly Query Syntax and Output

This simple example illustrates the query syntax, which performs a spatial search for images acquired with the DEIMOS instrument:

https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS

The search area (POS) and instrument (INSTRUMENT) are the only required search parameters. The query will return 117 records of images as of August 15, 2015 (more records may be found at later dates as more protected data become public). By default, the records are returned in VOTable format, a self-describing XML structure defined by the IVOA. (View a sample output file.) The interface can also return results in common ASCII formats such as CSV.

The output records include a link to the raw image files that users may access and download. They will also include a link to a text file containing a list of associated calibration files that will provide optimum calibration of the raw data. See https://koa.ipac.caltech.edu/UserGuide/calibration_association.html for details of the calibration association and how it is computed for each instrument. Browse-quality images of the raw data in JPEG format and images of processed data are currently accessible through the web interface at https://koa.ipac.caltech.edu/.

More complex queries that filter data files by parameters such as time, pixel scale, and exposure time are easy to build. Inclusive lower and upper bounds for parameter query ranges are separated by a forward slash ("/"). The input parameters accepted by the program interface are summarized below:

Parameter
(case insensitive)		 Description Required Format Unit Acceptable Values
(case insensitive)
POS Position with CIRCLE or POLYGON constraint Y integer, floating point, exponential degree 0.0 ≤ RA ≤ 360.0 deg
-90.0 ≤ Dec ≤ +90 deg

Example:
CIRCLE ra dec radius
POLYGON ra1 dec1... ra4 dec4
INSTRUMENT Single Instrument Y string   DEIMOS
ESI
LRIS
LWS
MOSFIRE
NIRC
NIRC2
NIRSPEC
OSIRIS
BAND Wavelength N integer, floating point, exponential meter Wavelength Coverage

Example:
0.03
0.03/0.05
TIME Time or time range of observation N string

date: yyyy-mm-dd

timestamp: yyyy-mm-ddThh:mm:ss[.SSS]

MJD		 timpstamp string, or [MJD], days DEIMOS: ≥ 2002-06-14
ESI: ≥ 1999-08-30
LRIS: ≥ 1994-06-08
LWS: 1998-12-03 to 2005-05-26
MOSFIRE: ≥ 2012-05-05
NIRC: 1995-03-16 to 2010-01-31
NIRC2: ≥ 2001-07-31
NIRSPEC: ≥ 2000-01-13
OSIRIS: ≥ 2005-03-28

Example:
2013-10-13/2013-10-17
2012-01-05T01:02:03.33
55123.456
FOV Field-of-view N integer, floating point, exponential degree DEIMOS: 0.30275367
ESI: 0.19615385
LRIS: 0.21722320
LWS: 0.00425898
MOSFIRE: 0.14473502
NIRC: 0.01508494
NIRC2: 0.00023509 to 0.01596430
NIRSPEC: 0.01790080
OSIRIS: 0.00804530

Example:
0/.02
SPATRES Pixel scale N integer, floating point, exponential arcsec/pixel DEIMOS: 0.119
ESI: 0.1542
LRIS: 0.135
LWS: 0.0847
MOSFIRE: 0.1799
NIRC: 0.15
NIRC2: 0.009952 to 0.039686
NIRSPEC: 0.178
OSIRIS: 0.020

Example:
1.2e-5
EXPTIME Exposure Time N integer, floating point, exponential second ≥ 0.0

Example:
2.5
ID identifier of dataset N string   KOAID string

Example:
LR.20060503.51317.fits LR.20060503
TARGET Target N string   Any string value

Example:
H1543
COLLECTION Data Collection N string   KOA
(default if omitted)
FACILITY Facility or Telescope N string   Keck
(default if omitted)
DPTYPE Data Product Type N string   image
(default if omitted)
CALIB Calibration level N integer   0
(default if omitted)
FORMAT Data format N string   FITS
(default if omitted)
MAXREC Maximum records returned N integer   ≥ 0
(no limit if omitted)

Example:
10000
RESULTFORMAT
or
RESPONSEFORMAT		 Format of output records N string   votable (default if omitted)
csv
html
ipac
json
tab
The following parameters described in the SIA v2 protocol are not supported here and they will be ignored if included in a query
POL Polarization N string    
SPECRP Spectral Resolving Power N integer    
TIMERES Temporal Resolution N integer, floating point, exponential    
UPLOAD Not yet defined in the protocol N      

 

Wavelength Coverage ("BAND")

The records returned in response to a query for data covering a particular wavelength or wavelength range, specified through the BAND parameter, require special consideration. The table below records the wavelength range covered by each instrument, returned keywords, and the unit of the returned wavelength. BAND searches for NIRC2, NIRSPEC, and OSIRIS will return records of observations if the user-specified range overlaps any part of the user-specified range. BAND searches for all other instruments will return records of observations that overlap any part of the instrument wavelength range.

Instrument Wavelength range
(meter)		 Returned Wavelenth Keyword Returned Wavelength Unit
DEIMOS 0.41 - 1.1 e-06 wbluinst
wredinst		 µm
ESI 0.39 - 1.1 e-06 wbluinst
wredinst		 µm
LRIS Blue: 0.33 - 0.68 e-06
Red: 0.38 - 1.1 e-06		 wbluinst
wredinst		 µm
LWS 3.0 - 25.0 e-06 wbluinst
wredinst		 µm
MOSFIRE 0.9 - 2.5 e-06 wbluinst
wredinst		 µm
NIRC 0.8 - 5.3 e-06 wbluinst
wredinst		 µm
NIRC2 0.95 - 5.3 e-06 WAVEBLUE
WAVERED		 µm
NIRSPEC 0.95 - 2.5 e-06 WAVEBLUE
WAVERED		 µm
OSIRIS 0.95 - 2.5 e-06 WAVEBLUE
WAVERED		 nm

 

Examples

The examples show how the above parameters are used in practice, organized by instrument. The number of records returned is accurate as of August 15, 2015 (more records may be returned at later dates as more protected data become public). You may run these queries as-is, or you may modify them according to needs. The query parameters are shown as upper-case for presentation, but they are case insensitive in practice.

Skip to:

DEIMOS

  1. Search for all DEIMOS images within a 5 deg radius of RA =150 deg, Dec =45 deg:

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS

    Returns 117 records in VOTable format.

  2. Search for all DEIMOS images within a 5 deg radius of RA =150 deg, Dec =45 deg, and return results in Comma Separated Values (CSV) format.

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS&RESULTFORMAT=csv

    Returns 117 records in CSV format.

  3. Search for all DEIMOS images within a 5 deg radius of RA =150 deg, Dec =45 deg, for a date range of 2002 June 14 to 2002 June 16, and return results in IPAC table format.

    4. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS&TIME=2002-06-14T00:00:00/2002-06-16T10:00:00&RESULTFORMAT=ipac

    Returns 5 records in IPAC table format.

  4. Search for all DEIMOS images within a box bounded by the RA and DEC values [145,40; 145,60; 155,60; 155,40] deg, for a date range of 2002 June 14 to 2002 June 16, and return results in IPAC table format.

    5. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=POLYGON 145 40 145 60 155 60 155 40&INSTRUMENT=DEIMOS&TIME=2002-06-14T00:00:00/2002-06-16T10:00:00&RESULTFORMAT=ipac

    Returns 5 records in IPAC Table.

These examples return results in columns defined as follows:

Column
Name		 Description unit Corresponding
FITS Keyword
ra Right ascension (J2000) of the observed target

 degree

 RA
dec

 Declination (J2000) of the observed target

 degree

 DEC
instrume

 Instrument name

  

 INSTRUME
elaptime

 Total exposure time

 second

 ELAPTIME
utc

 Coordinated universal time at the start of the exposure

  

 UTC
targname

 Target name

  

 TARGNAME
koaid

 Unique file identifier assigned by KOA

  

 KOAID
NAXIS1

 Number of columns in image

  

 NAXIS1
NAXIS2

 Number of rows in image

  

 NAXIS2
DATE_OBS

 UT date of observation at the start of the exposure

  

 DATE-OBS
MJD_OBS

 Modified Julian Date of observation

  

 MJD-OBS
FILTER

 Filter name or position

  

 DWFILNAM
SLITNAME

 Slitmask name

  

 SLMSKNAM
SPATRES

 Spatial resolution

 arcsec/pixel

  
CALIB

 Calibration level of data

  

  
FACILITY

 Name of the facility where the data were acquired

  

 TELESCOP
size

 Image file size

 byte

  
wbluinst

 Approximate blue end wavelength of the instrument

 µm

  
wredinst

 Approximate red end wavelength of the instrument

 µm

  
angleDistance

 Angular distance between (ra, dec) and the center of the region (POS) specified in the query

 degree

  
url Link to image files discovered in KOA (FITS)    
calibfiles Link to associated calibration files (text file)    


ESI

  1. Search for all ESI data within a 2 deg radius of RA=238.0 deg, Dec=-17.0 deg and observation date between Dec. 18, 2003 and Dec. 20, 2003:

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 238.0 -17.0 2.0&INSTRUMENT=ESI&TIME=2003-12-18/2003-12-20&RESULTFORMAT=votable

    Returns 36 records in the VOTable format.

  2. Search for all ESI data within a 2 deg radius of RA=238.0 deg, Dec=-17.0 deg and with exposure times between 15 and 30 sec:

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 238.0 -17.0 2.0&INSTRUMENT=ESI&EXPTIME=15/30&RESULTFORMAT=votable

    Returns 26 records in VOTable format.

  3. Search for all ESI data within a 2 deg radius of RA=21.5 deg, Dec=0.5 with observation date after Dec. 18, 2003 00:00:00 UT and target name like "J0121:"

    4. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 21.5 0.5 2.0&INSTRUMENT=ESI&TIME=2003-12-18/&TARGET=J0121&RESULTFORMAT=tab

    Returns 3 records in tab-delimited format.

These examples return results in columns defined as follows:

Column
Name		 Description unit Corresponding
FITS Keyword
ra Right ascension (J2000) of the observed target degree RA
dec Declination (J2000) of the observed target degree DEC
instrume Instrument name   INSTRUME
elaptime Total exposure time second ELAPTIME
utc Coordinated universal time at the start of the exposure   UTC
targname Target name   TARGNAME
koaid Unique file identifier assigned by KOA   KOAID
NAXIS1 Number of columns in image   NAXIS1
NAXIS2 Number of rows in image   NAXIS2
DATE_OBS UT date of observation at the start of the exposure   DATE-OBS
MJD_OBS Modified Julian Date of observation   MJD-OBS
FILTER Filter name or position   DWFILNAM
SLITNAME Slitmask name   SLMSKNAM
SPATRES Spatial resolution arcsec/pixel  
CALIB Calibration level of data    
FACILITY Name of the facility where the data were acquired   TELESCOP
size Image file size byte  
wbluinst

 Approximate blue end wavelength of the instrument

 µm

  
wredinst

 Approximate red end wavelength of the instrument

 µm

  
angleDistance Angular distance between (ra, dec) and the center of the region (POS) specified in the query degree  
url Link to image files discovered in KOA (FITS)    
calibfiles Link to associated calibration files (text file)    


LRIS

  1. Search for all LRIS data within 5 deg of RA=230.0 deg, Dec=-1.0 deg with exposure time ≤35 sec, and observation date between May 2, 2006 and May 4, 2006:

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 230.0 -1.0 5.0&INSTRUMENT=LRIS&TIME=2006-05-02T16:00:00.00/2006-05-04T16:00:00&EXPTIME=/35.0&RESULTFORMAT=ipac

    Returns 41 records in IPAC table format.

  2. Search for all LRIS data within 5 deg of RA=230.0 deg, Dec=-1.0 deg and with a target name like "L107:"

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 230.0 -1.0 5.0&INSTRUMENT=LRIS&TARGET=L107&RESULTFORMAT=html

    Returns 79 records in HTML format.

These examples return results in columns defined as follows:

Column
Name		 Description unit Corresponding
FITS Keyword
ra Right ascension (J2000) of the observed target degree RA
dec Declination (J2000) of the observed target degree DEC
instrume Instrument name   INSTRUME
elaptime Total exposure time second ELAPTIME
utc Coordinated universal time at the start of the exposure   UTC
targname Target name   TARGNAME
koaid Unique file identifier assigned by KOA   KOAID
NAXIS1 Number of columns in image   NAXIS1
NAXIS2 Number of rows in image   NAXIS2
DATE_OBS UT date of observation at the start of the exposure   DATE-OBS
MJD_OBS Modified Julian Date of observation   MJD-OBS
FILTER Filter name or position   REDFILT,BLUFILT
SLITNAME Slitmask name   SLITNAME
SPATRES Spatial resolution arcsec/pixel  
CALIB Calibration level of data    
FACILITY Name of the facility where the data were acquired   TELESCOP
size Image file size byte  
wbluinst

 Approximate blue end wavelength of the instrument

 µm

  
wredinst

 Approximate red end wavelength of the instrument

 µm

  
angleDistance Angular distance between (ra, dec) and the center of the region (POS) specified in the query degree  
url Link to image files discovered in KOA (FITS)    
calibfiles Link to associated calibration files (text file)    


LWS

  1. Search for all LWS data within 5 deg of RA=231.75 deg, Dec=+35.978 deg:

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE+231.75+35.978+5.0&INSTRUMENT=LWS&COLLECTION=KOA&FACILITY=Keck&resultformat=votable

    Returns 15 records in VOtable format.

  2. Search for all LWS data within 5 deg of RA=231.75 deg, Dec=+35.978 deg, with a target name like "IRAS" and observed before 2002-02-23:

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE+231.75+35.978+5.0&INSTRUMENT=LWS&COLLECTION=KOA&FACILITY=Keck&TIME=/2002-02-23T00:00:00&TARGET=IRAS&resultformat=ipac

    Returns 7 records in IPAC format.

These examples return results in columns defined as follows:

Column
Name		 Description unit Corresponding
FITS Keyword
ra Right ascension (J2000) of the observed target degree RA
dec Declination (J2000) of the observed target degree DEC
instrume Instrument name   INSTRUME
elaptime Total exposure time second ELAPTIME
utc Coordinated universal time at the start of the exposure   UTC
koaid Unique file identifier assigned by KOA   KOAID
targname Target name   TARGNAME
NAXIS1 Number of columns in image   NAXIS1
NAXIS2 Number of rows in image   NAXIS2
DATE_OBS UT date of observation at the start of the exposure   DATE-OBS
MJD_OBS Modified Julian Date of observation   MJD-OBS
FILTER Filter name or position   FILNAME
SLITNAME Slitmask name   APNAME
SPATRES Spatial resolution arcsec/pixel  
CALIB Calibration level of data    
FACILITY Name of the facility where the data were acquired   TELESCOP
size Image file size byte  
wbluinst

 Approximate blue end wavelength of the instrument

 µm

  
wredinst

 Approximate red end wavelength of the instrument

 µm

  
angleDistance Angular distance between (ra, dec) and the center of the region (POS) specified in the query degree  
url Link to image files discovered in KOA (FITS)    
calibfiles Link to associated calibration files (text file)    


MOSFIRE

  1. Search for all MOSFIRE data within 2.5 deg of RA=32.0 deg, Dec=-1.0 deg and observation date between Sept. 12, 2012 and Sept. 15, 2012:

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 32.0 -1.0 2.5&INSTRUMENT=MOSFIRE&TIME=2012-09-12/2012-09-15&RESULTFORMAT=csv

    Returns 31 records in a CSV (comma separated value) table.

  2. Search for all MOSFIRE data within 2.5 deg of RA=32.0, Dec=-1.0 with observation date between Sept. 12, 2012 and Sept. 15, 2012 and a total exposure time ≤60 sec:

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 32.0 -1.0 2.5&INSTRUMENT=MOSFIRE&TIME=2012-09-12/2012-09-15&EXPTIME=/60&RESULTFORMAT=votable

    Returns 10 results as a VOTable.

These examples return results in columns defined as follows:

Column
Name		 Description unit Corresponding
FITS Keyword
ra Right ascension (J2000) of the observed target degree RA
dec Declination (J2000) of the observed target degree DEC
crota2 Rotation angle of the image (from North through East) degree CROTA2
instrume Instrument name   INSTRUME
elaptime Total exposure time second ELAPTIME
utc Coordinated universal time at the start of the exposure   UTC
targname Target name   TARGNAME
koaid Unique file identifier assigned by KOA   KOAID
NAXIS1 Number of columns in image   NAXIS1
NAXIS2 Number of rows in image   NAXIS2
DATE_OBS UT date of observation at the start of the exposure   DATE-OBS
MJD_OBS Modified Julian Date of observation   MJD-OBS
FILTER Filter name or position   FILTER
SLITNAME Slitmask name   MASKNAME
SPATRES Spatial resolution arcsec/pixel PSCALE
CALIB Calibration level of data    
FACILITY Name of the facility where the data were acquired   TELESCOP
size Image file size byte  
wbluinst

 Approximate blue end wavelength of the instrument

 µm

  
wredinst

 Approximate red end wavelength of the instrument

 µm

  
angleDistance Angular distance between (ra, dec) and the center of the region (POS) specified in the query degree  
url Link to image files discovered in KOA (FITS)    
calibfiles Link to associated calibration files (text file)    


NIRC

  1. Search for all NIRC images within a 7 deg radius of RA=171.0 and Dec= 58.0

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 171.0 58.0 7.0&INSTRUMENT=NIRC

    Returns 813 records in VOTable format

  2. Search for all NIRC images within a 7 deg radius of RA=171.0 and Dec= 58.0 within a time range of 49,800 to 49,900 seconds , and return the result in csv format.

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 171.0 58.0 7.0&INSTRUMENT=NIRC&BAND=1.0e-06/2.0e-06&TIME=49800/49900&RESULTFORMAT=csv

    Returns 96 records in CSV format

  3. Search for NIRC images within a 7 deg radius of RA=171.0 and Dec= 58.0 within a time range of 49,800 to 49,900 seconds , with a field of view of between 0.01 and 0.02 degrees and return the result in IPAC format.

    4. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 171.0 58.0 7.0&INSTRUMENT=NIRC&BAND=1.0e-06/2.0e-06&TIME=49800/49900&FOV=0.01/0.02&RESULTFORMAT=IPAC

    Returns 96 records in IPAC table format

These examples return results in columns defined as follows:

Column
Name		 Description unit Corresponding
FITS Keyword
ra Right ascension (J2000) of the observed target degree RA
dec Declination (J2000) of the observed target degree DEC
instrume Instrument name   INSTRUME
elaptime Total exposure time second ELAPTIME
utc Coordinated universal time at the start of the exposure   UTC
targname Target name   TARGNAME
koaid Unique file identifier assigned by KOA   KOAID
NAXIS1 Number of columns in image   NAXIS1
NAXIS2 Number of rows in image   NAXIS2
DATE_OBS UT date of observation at the start of the exposure   DATE-OBS
MJD_OBS Modified Julian Date of observation   MJD-OBS
FILTER Filter name or position   FILTER
SLITNAME Slitmask name   SLTNAME
SPATRES Spatial resolution arcsec/pixel  
CALIB Calibration level of data    
FACILITY Name of the facility where the data were acquired    
size Image file size byte  
wbluinst

 Approximate blue end wavelength of the instrument

 µm

  
wredinst

 Approximate red end wavelength of the instrument

 µm

  
angleDistance Angular distance between (ra, dec) and the center of the region (POS) specified in the query degree  
url Link to image files discovered in KOA (FITS)    
calibfiles Link to associated calibration files (text file)    


NIRC2

  1. Search for all NIRC2 data within 5 deg of RA=69.0 deg, Dec=-2.5 deg observed between Nov. 28, 2001 and Nov. 30, 2001 and that covers wavelengths ≤2.0 µm (2e-6 meters):

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 69.0 -2.5 5.0&INSTRUMENT=NIRC2&BAND=/2.0e-6&TIME=2001-11-28/2001-11-30&RESULTFORMAT=votable

    Returns 29 records in VOTable format.

  2. Search for all NIRC2 data within the box defined by the RA, Dec pairs [70.0,-3.0; 68.0,-3.0; 67.0,-2.0; 70.0,-2.2] degree and observed between Nov. 28, 2001 and Nov. 30, 2001:

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=polygon 70.0 -3.0 68.0 -3.0 67.0 -2.0 70.0 -2.2&INSTRUMENT=NIRC2&TIME=2001-11-28/2001-11-30&RESULTFORMAT=votable

    Returns 60 records in VOTable format.

These examples return results in columns defined as follows:

Column
Name		 Description unit Corresponding
FITS Keyword
ra Right ascension (J2000) of the observed target degree RA
dec Declination (J2000) of the observed target degree DEC
crota2 Rotation angle of the image (from North through East) degree CROTA2
instrume Instrument name   INSTRUME
elaptime Total exposure time second ELAPTIME
utc Coordinated universal time at the start of the exposure   UTC
targname Target name   TARGNAME
OBJECT Object name   OBJECT
koaid Unique file identifier assigned by KOA   KOAID
NAXIS1 Number of columns in image   NAXIS1
NAXIS2 Number of rows in image   NAXIS2
DATE_OBS UT date of observation at the start of the exposure   DATE-OBS
MJD_OBS Modified Julian Date of observation   MJD-OBS
FILTER Filter name or position   FILTER
SLITNAME Slitmask name   SLITNAME
SPATRES Spatial resolution arcsec/pixel PIXSCALE
CALIB Calibration level of data   DATLEVEL
FACILITY Name of the facility where the data were acquired   TELESCOP
WAVEBLUE Approximate blue end of wavelength µm WAVEBLUE
WAVERED Approximate red end of wavelength µm WAVERED
size Image file size byte  
angleDistance Angular distance between (ra, dec) and the center of the region (POS) specified in the query degree  
url Link to image files discovered in KOA (FITS)    
calibfiles Link to associated calibration files (text file)    


NIRSPEC

  1. Search for NIRSPEC imaging data within 5 deg of RA=15.0 deg, Dec=70 deg observed between the MJD of 51700 days and 52000 days with an exposure time ≤12.0 sec and a target name containing the text "AO:"

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 15.0 70.0 5.0&INSTRUMENT=NIRSPEC&TIME=51700/52000&EXPTIME=/12.0&TARGET=AO&RESULTFORMAT=ipac

    Returns 88 records in IPAC table format.

  2. Same as above, but restrict the wavelength coverage to ≤ 1.5 µm (1.5e-6 meters):

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 15.0 70.0 5.0&INSTRUMENT=NIRSPEC&BAND=/1.5e-6&TIME=51700/52000&EXPTIME=/12.0&TARGET=AO&RESULTFORMAT=ipac

    Returns 35 records in IPAC table format.

These examples return results in columns defined as follows:

Column
Name		 Description unit Corresponding
FITS Keyword
ra Right ascension (J2000) of the observed target degree RA
dec Declination (J2000) of the observed target degree DEC
instrume Instrument name   INSTRUME
elaptime Total exposure time second ELAPTIME
utc Coordinated universal time at the start of the exposure   UTC
targname Target name   TARGNAME
OBJECT Object name   OBJECT
koaid Unique file identifier assigned by KOA   KOAID
NAXIS1 Number of columns in image   NAXIS1
NAXIS2 Number of rows in image   NAXIS2
DATE_OBS UT date of observation at the start of the exposure   DATE-OBS
MJD_OBS Modified Julian Date of observation   MJD-OBS
FILTER Filter name or position   FILNAME
SLITNAME Slitmask name   SLITNAME
SPATRES Spatial resolution arcsec/pixel SPATSCAL
CALIB Calibration level of data   DATLEVEL
FACILITY Name of the facility where the data were acquired   TELESCOP
WAVEBLUE Approximate blue end of wavelength µm WAVEBLUE
WAVERED Approximate red end of wavelength µm WAVERED
size Image file size byte  
angleDistance Angular distance between (ra, dec) and the center of the region (POS) specified in the query degree  
url Link to image files discovered in KOA (FITS)    
calibfiles Link to associated calibration files (text file)    


OSIRIS

  1. Search for all OSIRIS imaging data within 5 deg of RA=46.0 deg, Dec=0.12 deg observed between Aug. 9, 2007 and Aug. 11, 2007:

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 46.0 0.12 5.0&INSTRUMENT=OSIRIS&TIME=2007-08-09/2007-08-11&RESULTFORMAT=ipac

    Returns 21 records in IPAC table format.

  2. Same as above but restrict the wavelength coverage 2.1-2.3 µm (2.1e-6 to 2.3e-6 meters) and return a VOTable:

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 46.0 0.12 5.0&INSTRUMENT=OSIRIS&BAND=2.1e-6/2.3e-6&TIME=2007-08-09/2007-08-11&RESULTFORMAT=votable

    Returns 7 records in VOTable format.

These examples return results in columns defined as follows:

Column
Name		 Description unit Corresponding
FITS Keyword
ra Right ascension (J2000) of the observed target degree RA
dec Declination (J2000) of the observed target degree DEC
crota2 Rotation angle of the image (from North through East) degree CROTA2
instrume Instrument name   INSTRUME
elaptime Total exposure time second ELAPTIME
utc Coordinated universal time at the start of the exposure   UTC
targname Target name   TARGNAME
OBJECT Object name   OBJECT
koaid Unique file identifier assigned by KOA   KOAID
NAXIS1 Number of columns in image   NAXIS1
NAXIS2 Number of rows in image   NAXIS2
DATE_OBS UT date of observation at the start of the exposure   DATE-OBS
MJD_OBS Modified Julian Date of observation   MJD-OBS
FILTER Filter name or position   IFILTER
SPATRES Spatial resolution arcsec/pixel CDELT1
CALIB Calibration level of data   DATLEVEL
FACILITY Name of the facility where the data were acquired    
WAVEBLUE Approximate blue end of wavelength nm WAVEBLUE
WAVERED Approximate red end of wavelength nm WAVERED
size Image file size byte  
angleDistance Angular distance between (ra, dec) and the center of the region (POS) specified in the query degree  
url Link to image files discovered in KOA (FITS)    
calibfiles Link to associated calibration files (text file)    

 

Examples of Queries with Invalid Inputs

In these examples, the service call will return a message notifying you where the query parameters are invalid.

  1. Missing required parameter. Search for all data within a 5 deg radius of RA=150 deg, Dec=45 deg.

    2. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0

    Returns the message:

    INSTRUMENT is not found or has empty value in URL. INSTRUMENT and POS are required parameters in URL.

    Solution: Add the INSTRUMENT parameter:

    https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS

  2. Date format is incorrect. Search for DEIMOS data between June 14, 2002 and June 16, 2002:

    3. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS&TIME=June 14 2002/June 16 2002&FOV=0.3/0.6&SPATRES=0.1/0.15&EXPTIME=/200.0&RESULTFORMAT=ipac

    Returns the message:

    TIME = June 14 2002/June 16 2002 => Wrong format of first time value. Time value should be in the form of yyyy-mm-dd, yyyy-mm-ddThh:mm:ss[.SSS], or a floating point number (ex. 56155.77889) for MJD.

    Solution: Put time in the correct format:

    https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS&TIME=2002-06-14T00:00:00/2002-06-16T10:00:00&FOV=0.3/0.6&SPATRES=0.1/0.15&EXPTIME=/200.0&RESULTFORMAT=ipac

  3. Incorrect use of delimiter. Search for DEIMOS images with an exposure time of <+200s

    4. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS&TIME=2002-06-14T00:00:00/2002-06-16T10:00:00&FOV=0.3/0.6&SPATRES=0.1/0.15&EXPTIME=<+200.0&RESULTFORMAT=ipac

    Returns the message:

    EXPTIME = <+200.0 => Wrong format of first numeric value. The numeric value should be like an integer, a floating point number or a number with an exponent, such as 222.3333, 33, .223, 2.7e10, .7E-2, etc.

    Solution: Use the correct delimiter:

    https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS&TIME=2002-06-14T00:00:00/2002-06-16T10:00:00&FOV=0.3/0.6&SPATRES=0.1/0.15&EXPTIME=/200.0&RESULTFORMAT=ipac

  4. Range character in the date is backward slash ( \ ) instead of forward slash ( / ). Search for OSIRIS data between Aug. 9, 2007 and Aug. 11, 2007:

    5. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 46.0 0.12 5.0&INSTRUMENT=OSIRIS&TIME=2007-08-09\2007-08-11&RESULTFORMAT=votable

    Returns the message:

    TIME = 2007-08-09\2007-08-11 => Wrong format of first time value. Time value should be in the form of yyyy-mm-dd, yyyy-mm-ddThh:mm:ss[.SSS], or a floating point number (ex. 56155.77889) for MJD.

    Solution: Change the direction of the slash in the date:

    https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 46.0 0.12 5.0&INSTRUMENT=OSIRIS&TIME=2007-08-09/2007-08-11&RESULTFORMAT=votable

  5. POLYGON region does not contain four corners. Search for NIRC2 data bounded by the corners RA,Dec = [70.0,-3.0; 68.0,-3.0; 67.0,-2.0]

    6. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=polygon 70.0 -3.0 68.0 -3.0 67.0 -2.0&INSTRUMENT=NIRC2&TIME=2001-11-28/2001-11-30&RESULTFORMAT=votable

    Returns the message:

    POS value error. Format of four sided box region: POLYGON ra1 dec1 ... ra4 dec4 (numeric values in degree)

    Solution: Add a fourth corner to the POLYGON region

    https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=polygon 70.0 -3.0 68.0 -3.0 67.0 -2.0 70.0 -2.0&INSTRUMENT=NIRC2&TIME=2001-11-28/2001-11-30&RESULTFORMAT=votable

  6. The COLLECTION value is incorrect for KOA. Search for DEIMOS data in the "keck" collection:

    7. https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS&TIME=2002-06-14T00:00:00/2002-06-16T10:00:00&FOV=0.3/0.6&SPATRES=0.1/0.15&EXPTIME=/200.0&COLLECTION=keck&RESULTFORMAT=votable

    Returns the message:

    COLLECTION = keck => invalid collection name

    Solution: Change the value of COLLECTION from "keck" to "koa:"

    https://koa.ipac.caltech.edu/cgi-bin/VOServ/nph-searchImage?POS=CIRCLE 150.0 45.0 5.0&INSTRUMENT=DEIMOS&TIME=2002-06-14T00:00:00/2002-06-16T10:00:00&FOV=0.3/0.6&SPATRES=0.1/0.15&EXPTIME=/200.0&COLLECTION=koa&RESULTFORMAT=votable

 

Troubleshooting: What To Do When You Get a Message


KOA Image Access Program Interface Messages
VO Service Initialization Errors What To Do
VO configuration init error - config file open or parse error Problem is on the server. Please contact the KOA Help Desk.
VO instrument configuration init error - config file open or parse error Problem is on the server. Please contact the KOA Help Desk.
VO directory init error Problem is on the server. Please contact the KOA Help Desk.
Working directory configuration error Problem is on the server. Please contact the KOA Help Desk.
Log file creation error Problem is on the server. Please contact the KOA Help Desk.
SIA table map init error Problem is on the server. Please contact the KOA Help Desk.
Keyword or Format Errors What To Do
resultformat = xxx => not recognized Make sure that the output format is one of VOTable, IPAC, tab, CSV, HTML or json.
FORMAT = xxx => not valid Check that the FORMAT field is set to “FITS” (for KOA).
FORMAT = xxx => not match to KOA image format, “FITS” Check that the FORMAT field is set to “FITS.”
COLLECTION = xxx => invalid collection name Check that the COLLECTION field is set to “KOA.”
INSTRUMENT = xxx => invalid instrument name Check that the INSTRUMENT field is set to DEIMOS, ESI, LRIS, LWS, MOSFIRE, NIRSPEC, NIRC2 or OSIRIS.
keyword, "xxx", is not recognized Make sure the keyword is allowed by the service and compliant with the protocol.
POS is not found or has empty value in URL. INSTRUMENT and POS are required parameters in URL. Position (POS) is mandatory. Make sure you specify a position in Equatorial J2000 Coordinates.
INSTRUMENT is not found or has empty value in URL. INSTRUMENT and POS are required parameters in URL. INSTRUMENT is mandatory. Select one of the KOA instruments: DEIMOS, ESI, LRIS, LWS, MOSFIRE, NIRSPEC, NIRC2 or OSIRIS.
Keyword POS Value Errors What To Do
  • POS value error. POS="CIRCLE ra dec radius" (in degree) or "POLYGON ra1 dec1 ... ra4 dec4" (in degree, corners of a four sided box)

  • POS value error. Format of cone region: CIRCLE ra dec radius (numeric values in degree)

  • POS value error. Format of four sided box region: POLYGON ra1 dec1 ... ra4 dec4 (numeric values in degree)
Check whether the value of the keyword POS is in valid cone or four-sided box format.
Keyword Value Syntax and Semantics Errors

The error message is reported as
<parameter_name> = < value>, and the messages include:

 What To Do
  • Numeric value extraction error: memory allocation error
  • Wrong format of first (or second) numeric value. Regex compilation error.
  • Integer value extraction error: memory allocation error
  • Time value extraction error: memory allocation error
  • Wrong format of first (second) time value. Regex compilation error.
  • Wrong format of first (second) time value. Split date and time error.
 Please contact KOA Help Desk.
  • Wrong format of first (or second) numeric value. The numeric value should be like an integer, a floating point number or a number with an exponent, such as 222.3333, 33, .223, 2.7e10, .7E-2, etc.
Check if the value is in a valid floating number format.
  • Wrong format of first (or second) integer. The number should be a non-negative integer, such as 0, 1 or +1.
Check if the value is in a valid non-negative integer format.
  • First value should not be greater than the second value.
Check if the first number (lower bound) is not greater than the second number (upper bound).
  • Wrong format of first (second) time value. Time value should be in the form of yyyy-mm-dd, yyyy-mm-ddThh:mm:ss[.SSS], or a floating point number (ex. 56155.77889) for MJD.
  • Wrong format of first (second) time value. "The "month" number is out of range.
  • Wrong format of first (second) time value. The "date" number is out of range for leap year.
  • Wrong format of first (second) time value. The "date" number is out of range.
  • Wrong format of first (second) time value. The "hour" number is out of range.
  • Wrong format of first (second) time value. The "minute" number is out of range.
  • Wrong format of first (second) time value. The "second" number is out of range.
Check if the time value is in a valid format.

Check if the time value is in a valid number range for either the date or time portion.

  • First time value should not be greater than the second time value.
 Check that the first time value (lower bound) is not greater than the second time value (upper bound).
  • wrong string format
 Check whether the string contains valid characters including alphanumeric, period, and space.
(for fields of ID and FACILITY)
  • wrong data product type - it should be "image" or "cube."
 Check whether DPTYPE field is set to be either "cube" or "image." For KOA, "image" is the valid setting.
Image Discovery-Related Messages What To Do
search area error Problem is on the server. Please contact the KOA Help Desk.
column name collection error from search area table Problem is on the server. Please contact the KOA Help Desk.
search database error Problem is on the server. Please contact the KOA Help Desk.
update table column error Problem is on the server. Please contact the KOA Help Desk.
convert table format error Problem is on the server. Please contact the KOA Help Desk.
log file creation error Problem is on the server. Please contact the KOA Help Desk.
SIA table map init error Problem is on the server. Please contact the KOA Help Desk.
Status Messages What They Mean
(no action needed)
Total number of records returned = n

 n image files are found.

Zero records are returned

 Zero records are returned in the case of "MAXREC=0".

no data found

 No image files are found.



Last updated: 13 August 2015
 

Please acknowledge the use of KOA by including this text in your publications:

This research has made use of the Keck Observatory Archive (KOA), which is operated by the W. M. Keck Observatory and the NASA Exoplanet Science Institute (NExScI), under contract with the National Aeronautics and Space Administration.

Please also acknowledge the PI(s) of datasets that have been obtained through KOA, and please contact the KOA Help Desk if you publish archival data.

If your research uses data reduced by the DEIMOS DRP or MOSFIRE DRP, please use the PypeIt Citation.

Privacy Policy       Image Use Policy      

The Keck Observatory Archive (KOA) is a collaboration between the NASA Exoplanet Science Institute (NExScI) and the W. M. Keck Observatory (WMKO). NExScI is sponsored by NASA's Exoplanet Exploration Program, and operated by the California Institute of Technology in coordination with the Jet Propulsion Laboratory (JPL).

Google KOA WMKO
\#koashare.html\ Caltech     WMKO     NExScI     NASA