Overview

IRSA provides access to the ZTF collection of lightcurve data through an application program interface (API). Search, restriction, and formatting parameters are specified in an HTTP URL. The output is a table in the requested format containing lightcurve data satisfying the search constraints.

Important Note: To download large numbers of ZTF lightcurves, use the bulk download service available here: https://irsa.ipac.caltech.edu/data/ZTF/lc/lc_dr18 (Adjust the link to the latest release number as needed). Please contact the IRSA Help Desk with any questions: Help Desk.

Access Control: This section provides instructions and examples for accessing proprietary ZTF data.

Query

An IRSA ZTF-LC-API query returns a table (by default, a VOTable) containing lightcurve data corresponding to a set of ZTF objects and perhaps satisfying additional constraints. The query must specify, directly or indirectly, a set of ZTF objects for which lightcurve data is requested. In addition, it may specify the collection of ZTF lightcurve data files from which lightcurve data is to be retrieved, and it may indicate that only lightcurve data meeting certain restrictions is requested. Finally, the query may specify the format of the output.

IRSA ZTF-LC-API queries take the form of HTTP URLs whose parameters express the relevant requirements and constraints.

Parameter Purpose	Parameter Name
Specify ZTF objects by their identifiers	ID
Specify ZTF objects by position and other constraints	POS or CIRCLE, BAND, BANDNAME, NOBS_MIN, MAG
Restrict lightcurve data	TIME, BAD_CATFLAGS_MASK
Specify collection of ZTF lightcurve files	COLLECTION
Specify format of output table	FORMAT

These parameters are described individually below.

Behind the scenes

Typically there are multiple lightcurves for a given source position. Lightcurves are tagged in the ZTF lightcurve files by object identifier. As mentioned above, lightcurves corresponding to specific identifiers may be retrieved using the ZTF-LC-API via the ID parameter. Alternatively, this API also supports the retrieval of all lightcurves meeting positional and other constraints. When such constraints are supplied, a preliminary TAP query extracts the identifiers of all objects meeting those constraints from the ZTF objects table. Lightcurves corresponding to these identifiers are then retrieved from the ZTF lightcurve collection.

Sample queries

• Obtain the available g-band lightcurves within 5 arcsec of a source position:

  https://irsa.ipac.caltech.edu/cgi-bin/ZTF/nph_light_curves?POS=CIRCLE 298.0025 29.87147 0.0014&BANDNAME=g

• Perhaps two of the lightcurves in the previous response are of particular interest. Retrieve just these, filtering out bad data using a bit mask:

  https://irsa.ipac.caltech.edu/cgi-bin/ZTF/nph_light_curves?ID=686103400034440&ID=686103400106565&BAD_CATFLAGS_MASK=32768

• Obtain the available lightcurves within 5 arcsec of a source position which satisfy constraints on magnitude, band, and number of observations; further restrict lightcurve data based on time of observation; specify format of output table.

  https://irsa.ipac.caltech.edu/cgi-bin/ZTF/nph_light_curves?POS=CIRCLE 298.0 29.87 0.01&MAG=16.9 17.7&BAND=4.30e-7 5.70e-7&NOBS_MIN=5&TIME=55197.3 58329&FORMAT=ipac_table

Query Parameters

IRSA ZTF-LC-API queries are expressed as URLs. Names of supported query parameters and syntax of their values follow guidelines from the VO spec for SIA2, which are compatible with DALI and DataLink. In particular, elements of multi-element parameter values are separated by a single space. Ranges are represented by space-separated lower and upper bounds. Unrestricted lower (resp. upper) bounds are represented by the values -Inf (resp. Inf).

• The complete list of parameters supported by IRSA's ZTF-LC-API implementation is
  • ID
  • CIRCLE
  • POS
  • BAND
  • BANDNAME
  • MAG
  • NUM_OBS
  • TIME
  • BAD_CATFLAGS_MASK
  • COLLECTION
  • FORMAT
• Parameter names are case-insensitive.
• Every ZTF-LC-API query must contain exactly one of the following:
  • a single instance of the POS parameter
  • a single instance of the CIRCLE parameter
  • one or more instances of the ID parameter
• Parameters BAND, BANDNAME, NOBS_MIN, and MAG are compatible with POS and CIRCLE but not with ID.
• Parameters BAND, BANDNAME, MAG, and ID may appear more than once in a query; multiple values of a given parameter are OR'd together to create the associated constraint.
• Parameters CIRCLE, POS, BAND, MAG, and TIME accept or require values consisting of more than one element; these elements must be separated by a single space.

Parameter descriptions

Parameter Name	Parameter Description
ID	The ID parameter value is the identifier of a ZTF object. Example: ID=686103400067717
CIRCLE	The CIRCLE parameter value consists of 3 elements, all measured in degrees: RA (right ascension), DEC (declination), and RADIUS, in that order. RA and DEC are assumed to be in the ICRS system. As with other multi-element values, the elements must be separated by a single space. This parameter restricts ZTF objects of interest to the circle of radius RADIUS with center determined by RA and DEC. In accordance with the standard, the valid range of RA is [0,180] and of DEC is [-90,90]. For performance reasons, the valid range of RADIUS is limited to (0,0.1667]. Example: CIRCLE=-164.7 -5.8 0.1
POS	The POS parameter value must consist of a shape described by ICRS coordinates in decimal degrees. It identifies the shape which contains ZTF objects of interest. The only shape currently supported is CIRCLE. The three following elements of the value correspond to RA, DEC, and RADIUS respectively; see the description of CIRCLE above. Example: POS=circle -164.7 -5.8 0.1
BAND	The BAND parameter defines the wavelength interval, measured in meters, to be searched for data. This interval is unbounded by default. If (semi-)bounded, the interval includes the bounding value(s). A BAND constraint is satisfied if the interval intersects the wavelength coverage of the observation. Examples: Retrieve only data in the wavelength range 410nm—550nm: BAND=4.10e-7 5.50e-7 Retrieve data with wavelength no less than 1.4 micron: BAND=1.4e-6 Inf Retrieve data with wavelength no more than 1.4 micron: BAND=0 1.4e-6 Retrieve data that includes 2.2 micron: BAND=2.2e-6
BANDNAME	The BANDNAME parameter identifies by filter-id the wavelength interval(s) to be searched for data. Possible values are "g", "r", and "i", respectively equivalent to "1", "2" and "3", and comma-separated combinations thereof. Implemented as a filter on the "fid" column of the ZTF objects table. Examples: Find only G-band data, which covers the wavelength range 410nm—550nm: BANDNAME=g Find only G-band and I-band data, which cover the wavelength ranges 410nm—550nm and 700nm—900nm respectively: BANDNAME=g,i
MAG	The MAG parameter specifies a range in which the magnitude of ZTF objects of interest must lie. Implemented as a filter on the "medianmag" column of the ZTF objects table. Examples: MAG=17.0 17.7
NUM_OBS	The NUM_OBS parameter specifies the minimum number of observation epochs required of any ZTF object of interest. Implemented as a filter on the "nobs" column of the ZTF objects table. Examples: NUM_OBS=5
TIME	The TIME parameter specifies the date-time range for which lightcurve data is to be retrieved. The range is unlimited by default. Range endpoint(s) are interpreted as Modified Julian Dates (MJD). Implemented as a filter on the "mjd" field in the ZTF lightcurve collection. Examples: Retrieve only data in the MJD range 55555.5—555678.9: TIME=55555.5 55678.9 Retrieve only data from at or before the MJD time 55555.5: TIME=-Inf 55555.5 Retrieve only data from the MJD instant 55555.5: TIME=55555.5
BAD_CATFLAGS_MASK	The BAD_CATFLAGS_MASK parameter specifies a bitmask used to exclude lightcurve points with at least one of the indicated catflag bits set. (See e.g. Section 10.3 of The ZTF Science Data System Explanatory Supplement for a description of these bits.) Implemented as a filter on the "catflags" field in the ZTF lightcurve collection. Examples: Exclude any lightcurve point whose catflag value indicates at least one of the data issues associated to bits 0-3. BAD_CATFLAGS_MASK=15
COLLECTION	The COLLECTION parameter identifies the set of ZTF lightcurve files from which data will be returned, as well as the associated ZTF objects table. The default collection corresponds to the most recent public release. Currently supported values are "ztf" (login required) and "ztf_drN" where N can go back to include the last 5 versions. But the most recent release is preferred, so for the general user, COLLECTION need not be set. Examples: COLLECTION=ztf_dr18
FORMAT	The FORMAT parameter indicates the desired format of the output table. Possible values are VOTABLE (the default), IPAC_TABLE, HTML, CSV, and TSV (case-insensitive). Examples: FORMAT=VOTABLE

Access Control (only for non-public data)

The ZTF collection contains both proprietary and public (currently dr18) data. Access to proprietary data requires a password. General instructions for using the IRSA API's with a password are provided here; the following examples should suffice for ZTF-LC-API.

Examples:

1. Use curl to access proprietary data: curl --user myemail@astronomy.edu:mypassword -o out.tbl "https://irsa.ipac.caltech.edu/cgi-bin/ZTF/nph_light_curves?ID=686103400067717"


2. Use wget to access proprietary data: wget --auth-no-challenge --user=myemail@astronomy.edu --password=mypassword -O out.tbl "https://irsa.ipac.caltech.edu/cgi-bin/ZTF/nph_light_curves?ID=686103400067717"


3. Use curl with cookies and $USER and $PASS variables to access proprietary data: curl -c cookies.txt "https://irsa.ipac.caltech.edu/account/signon/login.do?josso_cmd=login&josso_username=$USER&josso_password=$PASS"

curl -b cookies.txt -o out.tbl "https://irsa.ipac.caltech.edu/cgi-bin/ZTF/nph_light_curves?ID=686103400067717"

curl -c cookies.txt "https://irsa.ipac.caltech.edu/account/signon/logout.do"


4. Use wget with cookies and $USER and $PASS variables to access proprietary data: wget --save-cookies=cookies.txt -O /dev/null "https://irsa.ipac.caltech.edu/account/signon/login.do?josso_cmd=login&josso_username=$USER&josso_password=$PASS"

wget --load-cookies=cookies.txt -O out.tbl "https://irsa.ipac.caltech.edu/cgi-bin/ZTF/nph_light_curves?ID=686103400067717"

wget --save-cookies=cookies.txt -O /dev/null "https://irsa.ipac.caltech.edu/account/signon/logout.do"

NOTE: Currently the cookie file issued using the last two examples above will be valid for 1 week, after which a new cookie file must be obtained. If requests are issued via a browser session that the user has logged into, note that login sessions will expire after 2 hours of inactivity, up to a maximum of 1 week.

Getting Help

If you've run into a problem, think you've found a bug, or simply have questions, please contact IRSA User Support.