Many of the interactive features inherent in the web interface, e.g., the visualization tools, are not available via the API.
The base URL for this service is https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?parameter=value¶meter=value...
The input parameters are specified by standard parameter/value pairs. For example, "locstr=m101" specifies the search center of the subset images. A URL that just specifies this location and nothing else looks like https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?locstring=m101 This query does not specify either the sizes of the images or the survey names, so the default values of all the rest of the parameters are used.
One command to execute this basic query with those most simple input parameters is:
wget --output-document=out.xml "https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?locstr=m101"Things to notice: It is https, not http. The URL is enclosed within quotes. The output is saved in out.xml, but if you have errors in your query, the file out.xml may not actually be xml but instead be html. It is the simplest query, only specifying a target, and the rest the parameters fall back to the defaults. You can use curl instead of wget; see below.
The output (saved in out.xml in the command above) is an XML document containing the URL of the corresponding interactive Finder Chart search results, and the URLs that point to the individual retrieved FITS images and the corresponding PNG images (both small and large).
Because the API queries result in XML tables, if you click on any of the example API links below, your browser may have trouble rendering it, or will render only bits and pieces of the embedded text. You may need to save the contents of the link to a file in order to read what is returned. You may be able to use "View Source" to see the result in more legible format.
Note that when you parse the XML file, you will be looking for URLs. To retrieve a URL using wget or curl, you should enclose the URL in quotes. Here are some examples:
wget --output-document=file.pdf "https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS,SDSS,2MASS,IRIS,WISE&locstr=291.468658447+40.343852997" curl --output file.pdf "https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS,SDSS,2MASS,IRIS,WISE&locstr=291.468658447+40.343852997" wget --output-document=file.xml "https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?subsetsize=15&survey=2MASS,AKARI,WISE,SEIP&locstr=247.025+-24.541667" curl --output file.xml "https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?subsetsize=15&survey=DSS,SDSS,2MASS,AKARI,WISE,SEIP&locstr=247.025+-24.541667"
Please note that it is really easy to inadvertently launch something that is functionally equivalent to a 'denial-of-service' attack on IRSA's servers if you are not careful. Please be sure to test your code using only a subset of your desired requests, and add throttle control to your code, e.g., add some 'wait' steps between successive requests. If we notice an undue load on our servers (a real life example is more than 70,000 requests over 10 hours, or an average of 2 per second), we may block your IP address, so if your requests suddenly stop working, this may be why. Please contact the IRSA Help Desk in this case.
Note that if you want to download PNG files via the API, there is currently no way to change the default stretch via the API.
The following table has the one required parameter (locstr) first, and then the rest of the parameters in alphabetical order.
|This input field must contain either a sky coordinate or an object name resolvable via NED or SIMBAD. If the input field contains a string which can be interpreted as a coordinate representation, it is used as such. Both decimal degree and sexagesimal notations are supported.||no default||
The "locstr" is the only required parameter; if it is an object
name, it is resolved into coordinates using NED and, if that fails,
The following are examples of acceptable name/coordinate formats:
must be used in conjunction with "mode"
|fits, pdf, png||fits||Specifies the desired output of a specific query. FITS, PDF, and PNG are the same options as when you select "Download" in the interactive GUI. The PDF option results in the PDF downloading; the rest are zip files of a subdirectory with the contents being the selected option (the FITS files or the PNG files). Note that this does not work for mode=getResult.|
|grid||true or false||false||Specifies whether or not a grid should be added to the PNG images. Note that this does not work for mode=getResult.|
|marker||true or false||false||Specifies whether or not a location marker should be added to the PNG images. Note that this does not work for mode=getResult.|
|marker_color||Basic color names in lowercase or HEX value||red||Specifies the color of the marker. 'marker' option must be set to true. Color name may be one of black, aqua, blue, cyan, fuchsia, gray, green, lime, magenta, maroon, navy, olive, orange, pink, purple, red, silver, teal, white, or yellow. Note that this does not work for mode=getResult.|
|marker_size||integer||4||Specifies the size of the circle marker, in px. 'marker' option must be set to true. Size must be greater than 0. The overlay symbol is a circle whose diameter is 2 times the marker_size in px. Note that this does not work for mode=getResult.|
|mode||prog, getImage, getResult||prog||Specifies the format of the returned file; "prog" (default) yields the XML format, and "getImage" retrieves the file given by the "file_type" parameter. Another option, "getResult", can be used in the URL to spawn a Finder Chart session with the results in the browser.|
|subsetsize||a decimal number||5||Specifies the cutout size of the retrieved images in arcmin. It should be between 0.1 and 60.0 arcmin.|
|survey||DSS, SDSS, 2MASS, WISE, SEIP, AKARI, IRAS||DSS, SDSS, 2MASS, WISE, IRAS||Specifies the survey dataset to be retrieved. ("IRIS" can be used instead of "IRAS" for the same image set.) It can be specified parameter pair "survey=value" (e.g. "survey=SDSS"). To specify multiple datasets, simply add more to the query (e.g., "survey=SDSS,DSS,SEIP"). When unspecified, it defaults to retrieving the original five datasets.|
https://irsa.ipac.caltech.edu/applications/finderchart/applications/finderchart/servlet/Note that several of these queries return XML files, which need to be parsed to find, e.g., the PDF or PNG files. Some files that are returned are zipfiles containing components. Some output examples are given below.
The interaction above can be done in a variety of ways, ranging from simple scripting (using programs like 'wget') to integrated URL-access and XML-parsing in JAVA, PERL, Python, etc. Our XML is simple enough that if you do not have XML-parsing tools, simple pattern checking (manually built code or tools like PERL) should suffice.
The returned XML "inventory" contains a results HTML page which includes the rotated and scaled PNG images from the retrieved images so they are all same size and orientation for being useful as a Finder Chart. In addition, it contains the URLs of the retrieved FITS images, the scaled PNG images used in the HTML page, and the PNG images in the original size. It also contains the 2MASS glint and persistent artifacts tables if the 2MASS survey is queried.
Here are all of the XML tag names that can occur. Examples of returned queries are below.
|finderchart||The top tag of the XML file which contains a variable "status" indicating whether the query is successful; "ok" for successul query and "error" otherwise.|
|message||The error message when the query status is "error".|
|input||A section tag which contains several input parameter sub-tags.|
|locstr||Input objname or coordinate (examples above).|
|surveys||Surveys included in the query.|
|subsetsize||Image subset size in arcmin.|
|grid||A "true" or "false".|
|marker||A "true" or "false".|
|result||A section tag which contains sub-tags of all the results including the search coordinate (in equatorial, galactic, and ecliptic), the URL links to the retrieved FITS images, the PNG images, and the 2MASS glint and persistent artifact tables when the 2MASS survey is requested.|
|datatag||The datatag contains the parameters of the query which allows the same query to be reproduced at a later time. Please consult the datatag instruction document on how to rerun the query.|
|equCoord||The input location in the equatorial coordinate system and sexigesimal format.|
|galCoord||The input location in the galactic coordinate system.|
|eclCoord||The input location in the ecliptic coordinate system.|
|totalimages||The total number of images retrieved.|
|htmlfile||The URL of the HTML file that contains the finder chart results.|
|pdffile||The URL of the PDF file that contains the finder chart results.|
|image||This is a sub-tag of the "result" tag, but it is a section tag that contains the sub-tags of an image's information and URLs.|
|colorimage||This is a sub-tag of the "result" tag.|
|surveyname||The survey name of the retrieved image: SDSS, DSS, 2MASS, WISE, SEIP, AKARI, or IRAS. ("IRIS" can be used instead of "IRAS" for the same image set.)|
|band||The band name of the retrieved image. By default, all bands are returned.|
|obsdate||The observation date extracted from the retrieved FITS image.|
|fitsurl||The URL of the retrieved FITS image.|
|jpgurl||The URL of the PNG image which is the same resolution as the FITS image. (Note that the name of the tag incldues 'jpg' but it returns PNGs.)|
|shrunkjpgurl||The URL of the shrunken PNG image. (Note that the name of the tag includes 'jpg' but it returns PNGs.)|
|artifact||The sub-tag of the result, one for each survey.|
|arturl||The URL to get the artifacts for the survey.|
Once you have parsed the URLs out of the XML, you can retrieve the results using wget or curl. In order to do this, you should enclose the URL in quotes, and tell it what to do with the output. Here are some explicit examples of using quotes around URLs for wget or curl:
wget --output-document=file.pdf "https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS,SDSS,2MASS,IRIS,WISE&locstr=291.468658447+40.343852997" curl --output file.pdf "https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS,SDSS,2MASS,IRIS,WISE&locstr=291.468658447+40.343852997"
The simplest returned XML is an error message. Here is a screen shot of the source XML returned from example 9 above:
Example 6 is rendered in my browser (at least to start) as:
with additional image tags (not shown) for the other images returned.
As can be seen, the tags here reflect the tags listed in the Output Parameters above, and they change to reflect the query results accordingly.
Now, you can use the API to generate a URL to start a session. For example, clicking on this URL should launch a new browser window with images loaded that are centered on M101: https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getResult&locstr=m101
Note that the syntax is different than it has been before. Future development of this capability will use the API (e.g., the "mode=getResult"), not just URL construction.