For Developers

AstroPix currently supports two simple Application Programmer Interfaces (APIs) that may be used by developers to return information for external queries. These APIs are based on permalinks to specific advanced searches. Two table formats are offered: XML and JSON.

Creating a Link to a Feed

Any advanced search can be used as an API for accessing the list of images that match. Once you have a query that returns the images you desire, you can create a permalink to that search by clicking the "Link to this Search" button at the upper right of the search results.

This creates a persistent URL for that specific search which now includes two additional permalinks at the top of the search results: XML and JSON. These are just different formats in which the matching image metadata is returned.

The XML feed provides a subset of the standard AVM tags in an XML wrapper.

The JSON feed provides a full dump of all available metadata in JSON format.

Accessing Images

Individual images may be accessed using information in the feed using a standard URL format:

http://images.ipac.caltech.edu/PublisherID/ID/PublisherID_ID_NNN.jpg

PublisherID, ID: Standard identifiers associated with each image.

NNN: The dimension of the bounding box of the image:

  • 320
  • 500
  • 1024
  • 1280
  • 1600*
  • 3000*
  • 6000*
  • 12000*
  • 24000*

*These are only generated if the source image is this size or greater.

Icons are also available at these sizes:

  • 32
  • 64
  • 75
  • 100
  • 128
  • 240

All images are scaled to fit within the NNNxNNN bounding box, so either width or height may be smaller than the dimension. All of the full images are tagged with AVM metadata, while the icons are not (to reduce file size).

Currently there is no information in the API feeds on the maximum image dimension of the source image. Since images are only guaranteed to be up sampled to a bounding box of 1280 pixels, there is no simple way to determine whether an image is available at larger dimensions. However, it is possible to query the directory to see the full list of available images using the URL:

http://images.ipac.caltech.edu/PublisherID/ID/

Note that there will often be one additional image in the directory named using the largest dimension of the source image (unless this corresponds to one of the dimensions already listed above).

Using the APIs

Accessing either the XML or JSON streams can have a lag of several seconds, upwards of a minute if a large number of images are being fed into the stream. As such these feeds are better used as a periodic download that is then processed on the client machine.

Have you found an interesting use for the AstroPix APIs? We would love to hear from developers who are using this site for innovative applications, or who may have other ideas for useful APIs we do not yet support.