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 query 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.
The output is (generally) 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). You can specify a parameter if you just want one file type from the search results.
Because the API queries generally 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 of the URLs you can pull from the XML fles, which also demonstrate the use of quotes around URLs for wget or curl:
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 will 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 itself. (There wasn't any way to do this in the old Finder Chart either.) If you need a different default stretch, instead of using the API, break up your targets into lists of 1000 or less, and do a batch search. When the search returns, customize the stretch for the first object in your list, and then ask it to prepare the download, selecting PNGs as the download option, and the stretch (and other parameters) you have established for the first one in the list are propagated to all of the objects in the list.
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,
SIMBAD. When the "locstr" is a coordinate string such as "102.03730
+59.77120 ga", it should be URL-encoded following standard URL
encoding, with spaces replaced by "+" and the plus sign
indicating positive declination as %2B, e.g., as "102.03730+%2B59.77120+ga".
The following are examples of acceptable name/coordinate formats:
|file_type||fits, html, pdf, png||fits||Specifies the desired output of a specific query. FITS, HTML, 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, the PNG files, or the HTML and associated PNG files).|
|grid||true or false||false||Specifies whether or not a grid should be added to the PNG images.|
|marker||true or false||false||Specifies whether or not a location marker should be added to the PNG images.|
|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|
|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. Defaults to 4 when value is out of range. The overlay symbol is a circle whose diameter is 2 times the marker_size in px.|
|mode||prog, getImage||prog||Specifies the format of the returned file; "prog" yields the XML format, and "getImage" retrieves the file given by the "file_type" parameter.|
|orientation||right or left||left||Specifies whether to point the East axis to the left as specified in the FITS image or to flip the image so that East points to right while generating PNG images. North is up in all cases.|
|page_layout||OnePerTarget or OnePerSurvey||OnePerTarget||OnePerTarget -- lays out all of the images on one page. OnePerSurvey splits the images into multiple pages by survey. This option only makes sense in the context of PDF or HTML output.|
|reproject||true or false||false||Specifies whether to reproject and resample the images from different bands of a dataset to a uniform resolution while generating the PNG images. When this is chosen, these resampled images can be used to make color images. However, this option takes longer to run (about 3 minutes per image).|
|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, IRAS(IRIS)||all retrieved||Specifies the survey dataset to be retrieved; each parameter pair "survey=value" (e.g. "survey=SDSS") specifies one dataset. To specify multiple datasets, simply add more parameter pairs to the query (e.g., "survey=sdss&survey=dss"). When unspecified, it defaults to retrieving all five datasets.|
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; currently available surveys are: SDSS, DSS, 2MASS, WISE, and IRAS(IRIS).|
|subsetsize||Image subset size in arcmin.|
|orientation||The orientaion of the PNG images as either "left" or "right", as explained above.|
|reproject||A "true" or "false" value.|
|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, or IRAS(IRIS).|
|band||The band name of the retrieved image.|
|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%2CSDSS%2C2MASS%2CIRIS%2CWISE&locstr=291.468658447%2B40.343852997" curl --output file.pdf "https://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS%2CSDSS%2C2MASS%2CIRIS%2CWISE&locstr=291.468658447%2B40.343852997"
The simplest returned XML is an error message. Here is a screen shot of the source XML returned from example 8 above:
Example 6 is rendered in my browser (at least to start) as:
with additional image tags (not shown) for the other images returned. When I "View Source", I see (again, at least to start):
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.
All parameters must be present for this to work.
Deconstructing that URL, we have: the base URL: https://irsa.ipac.caltech.edu/applications/finderchart/#&id=Hydra_finderchart_finder_chart&projectId=finderchart which tells IRSA what service you want. Then we have, separated by ampersands (&) :