Finder Chart: API and URL Construction

Contents of page/chapter:
+Introduction
+API: Introduction
+API Input Parameters
+API Input Examples
+API Output Parameters
+API Output Examples
+URL Construction

 

Introduction

There are three ways to interact with Finder Chart in an automatic or semi-automatic fashion.

Batch searching
You can pass a list of up to 1000 sources to Finder Chart from the search screen, and then bundle up the results to download all at once in any of a variety of formats. More information on that is in the Basics of Searching section. This option is best if you don't want to write code to search and parse the results, and/or if you have at most a few thousand sources.

API, or application programming interface
An API, or application programming interface, is also known as a "command-line call" to the archive. It enables programs to interact with the SHA, search for data, and download it. You can write a program that will construct a series of URLs and query our server, resulting in XML files. Then you will need to write code to parse those XML files to obtain the links that you need to download the the data files meeting your search criteria. Much of the rest of this section describes the input and output parameters (with examples) for this API interface. Please note that it is really easy to inadvertently launch a 'denial-of-service' attack on IRSA's servers if you are not careful. Use this option with caution. This option is best if you are pulling images for many thousands of sources automatically. Most of the rest of this chapter covers the API.

URL construction
You can construct a long URL that provides to Finder Chart all of the information it needs such that when you load the URL (or click on such a link from another site), it automatically spawns the interactive web-based interface with the files pre-loaded. The last section in this chapter describes this. This option could be used, say, in a working web page that lists many targets, where individually spawned Finder Chart sessions and the resultant interactivity is useful, such as in a large research team where targets (and information about them) need to be shared or assessed, or in an educational setting.

API: Introduction

The Finder Chart service can be accessed via an HTTP/GET program interface (basically a really long URL) where the request is a set of parameter=value pairs, separated by ampersands (&). What is returned is an XML file containing metadata and URL links to download products with the related ancillary files. Below, we describe these input parameters and the columns returned.

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 http://irsa.ipac.caltech.edu/applications/finderchart/servlet/api?parameter=value&parameter=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 http://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.

API Input Parameters

The input parameters are entered as standard HTTP "parameter=value" pairs in HTTP/GET syntax. In this syntax, the parameter name is followed by an equals sign which is then followed by a value. These pairs are separated from each other by ampersand (&) characters. No extra spaces are allowed, and if the value needs to contain any spaces or special characters that might cause ambiguities, these spaces have to be encoded as shown in any HTTP or URL reference. In the rest of this section, we list the parameters. For examples, see later sections below.

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.

ParameterValuesDefaultDescription
locstr
(REQUIRED)
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:
  • m83
  • NGC+7479
  • 2MASXJ23045666%2B1219223
  • 17h+44m+34s+-27d+59m+13s+Equatorial+J2000
  • 23h04m56.63s%2B12d19m22.7s+Equ+J2000
  • 22h57m57.5s+%2B26d09m00.09s+Equatorial+B1950
  • 17h44m34s+-27d59m13s
  • 00h42m44.3s+%2B41d16m08s+b1950
  • 00:42:44.3+-41:16:08
  • 00+42+44.3+-41+16+08+b1983
  • 004244.3+-411608
  • 17h+-27d+Equ+J2000
  • 17h+-27d
  • 34.5565%2B54.2321+gal
  • 34.%2B54.+ecl
file_typefits, html, pdf, pngfitsSpecifies 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).
gridtrue or falsefalseSpecifies whether or not a grid should be added to the PNG images.
markertrue or falsefalseSpecifies whether or not a location marker should be added to the PNG images.
marker_colorBasic color names in lowercase or HEX valuered 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_sizeinteger4Specifies 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.
modeprog, getImageprogSpecifies the format of the returned file; "prog" yields the XML format, and "getImage" retrieves the file given by the "file_type" parameter.
orientationright or leftleftSpecifies 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_layoutOnePerTarget or OnePerSurveyOnePerTarget 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.
reprojecttrue or falsefalseSpecifies 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).
subsetsizea decimal number5Specifies 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.

API Input Examples

The following examples can be run by clicking their links; examples 1 through 8 produce valid results while 9 and 10 are examples of the error conditions. Note that all of these queries return XML files, which need to be parsed to find, e.g., the PDF or PNG files. Some output examples are given below.
  1. api?locstr=m101
    Retrieves images for the area centered on object "m101" (where the resolved coordinates come from NED) with default image size of 5.0 arcmin.

  2. api?locstr=m101&survey=2mass&reproject=true
    Retrieves 2MASS images for the area centered on object "m101" (where the resolved coordinates come from NED) with the default image size of 5.0 arcmin and with the reproject option turned on so the images will be reprojected.

  3. api?locstr=210.77805+%2B54.32714&subsetsize=4.0
    Retrieves images for the area centered on object at coordinates "210.77805 +54.32714" (14h03m06.73175s +54d19m37.7082s) and with image size of 4.0 arcmin.

  4. api?locstr=102.03730%2B+59.79745%2Bga&subsetsize=4.0
    Retrieves images for the area centered on the same position as the previous example, using Galactic coordinates "102.03730 +59.79745 ga" and with image size of 4.0 arcmin.

  5. api?locstr=m101&survey=2mass&survey=dss
    Retrieves 2MASS and DSS images for the area centered on object "m101" with the default image size of 5.0 arcmin.

  6. api?locstr=m101&survey=2mass&orientation=right
    Retrieves 2MASS images for the area centered on object "m101" and with default image size of 5.0 arcmin. Since the orientation is specified to be "right", the PNG images will be made with East to the right.

  7. api?locstr=m101&survey=2mass&grid=true&marker=true
    Retrieves 2MASS images for the area centered on object "m101" with default image size of 5.0 arcmin and draws both grid and input location marker on the original PNG images.

  8. api?locstr=m101&marker_color=yellow&marker=true&marker_size=20&page_layout=OnePerSurvey
    Retrieves images (including PDFs) for the area centered on object "m101" with default image size of 5.0 arcmin, with a large yellow marker overlaid, and (for the PDFs) one page per image set (survey).

  9. api?locstr=xxx
    The input location of this query is unresolvable, it produces the error condition: "Coordinate [xxx] lookup error: Invalid object name."

  10. api?locstr=m101&subsetsize=62.0
    The input search radius of this query is larger than 60.0 arcmin, it produces the error condition: "ERROR: Subimage size: [62.0] out of range."

  11. api?mode=getImage&file_type=pdf&subsetsize=5&survey=DSS%2CSDSS%2C2MASS%2CIRIS%2CWISE&locstr=291.468658447%2B40.343852997
    This requests the PDF file output for the given position, which includes 5 arcminute images from all 5 surveys.

API Output Parameters (in XML)

When you run a web application interactively, often the return is HTML text which is rendered in a browser and contains links to download additional data files. However, HTML is notoriously difficult to parse. So, in program mode, we instead return a simple XML document. This document can be rendered in a browser, but the normal use pattern is as follows: have your program make an HTTP request using the above parameters; retrieve the XML result into a file (or memory); have your program parse it; extract links to the desired final data files; and use these links (again from your program, using, e.g., wget) to retrieve the data.

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.

Tag nameDescription
finderchartThe top tag of the XML file which contains a variable "status" indicating whether the query is successful; "ok" for successul query and "error" otherwise.
messageThe error message when the query status is "error".
inputA section tag which contains several input parameter sub-tags.
locstrInput objname or coordinate (examples above).
surveysSurveys included in the query; currently available surveys are: SDSS, DSS, 2MASS, WISE, and IRAS(IRIS).
subsetsizeImage subset size in arcmin.
orientationThe orientaion of the PNG images as either "left" or "right", as explained above.
reprojectA "true" or "false" value.
gridA "true" or "false".
markerA "true" or "false".
resultA 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.
datatagThe 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.
equCoordThe input location in the equatorial coordinate system and sexigesimal format.
galCoordThe input location in the galactic coordinate system.
eclCoordThe input location in the ecliptic coordinate system.
totalimagesThe total number of images retrieved.
htmlfileThe URL of the HTML file that contains the finder chart results.
pdffileThe URL of the PDF file that contains the finder chart results.
imageThis 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.
colorimageThis is a sub-tag of the "result" tag.
surveynameThe survey name of the retrieved image: SDSS, DSS, 2MASS, WISE, or IRAS(IRIS).
bandThe band name of the retrieved image.
obsdateThe observation date extracted from the retrieved FITS image.
fitsurlThe URL of the retrieved FITS image.
jpgurlThe 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.)
shrunkjpgurlThe URL of the shrunken PNG image. (Note that the name of the tag includes 'jpg' but it returns PNGs.)
artifactThe sub-tag of the result, one for each survey.
arturlThe 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 "http://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 "http://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"

API Output Examples

Any of the input example links above will yield output, and if you click on them right now, your browser will attempt to render the retrieved results. Output that is XML (examples 1-10 above) may throw your browser a curve ball. Choose "View Source" within your browser to see everything that is returned. Output that is a zip file or pdf file (example 11) should be easily handled by your browser; as noted above, when using wget or curl, you should specify how it should save the results.

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.

URL Construction

You can construct a very long URL consisting largely of "parameter=value" pairs and launch an interactive browser Finder Chart session with images pre-loaded according to your parameters. For example, clicking on this URL should launch a new browser window with images loaded that are centered on ra,dec= 202.484, 47.231: http://irsa.ipac.caltech.edu/applications/finderchart/#&id=Hydra_finderchart_finder_chart&projectId=finderchart&UserTargetWorldPt=202.48417;47.23056;EQ_J2000&subsize=0.0375&sources=DSS,SDSS,2MASS,IRIS,WISE&DoSearch=true

All parameters must be present for this to work.

Deconstructing that URL, we have: the base URL: http://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 (&) :