The MAST Pan-STARRS catalog API provides an easy-to-use cross-match capability for Pan-STARRS.  This page shows examples using curl and Python.

Cross-matches using the catalog search form

The MAST Pan-STARRS catalog search interface includes a cross-match capability.  This requires several steps:

  1. Click the "Crossmatch a List of Targets" label to show the cross-match controls.
  2. Click the "Choose CSV file" to select a comma-separated values file with 'ra' and 'dec' columns.
  3. Enter a search radius.
  4. Click the orange "Search Catalog" button at the bottom of the page.
  5. Click the Export link (upper right on the search results) to download the results.

Doing this for a single source list is simple, but it can be tedious if you need to do it more than once. 

Curl example

The catalogs API can be used to do this same query with a single curl command.  Here is a sample command that cross-matches the PS1 catalog with a list of positions in the file sn2005.csv:

curl -F radius=0.000833 -F 'file=@sn2005.csv' \
	-X POST > sn2005.ps1.csv

This uses the crossmatch/upload.csv service to match the PS1 Mean Object catalog to a radius of 0.000833 degrees = 3 arcsec around the positions listed in the file  sn2005.csv.  Here is a sample of a few lines from the file:

37.68021,-2.93883,SN 2005A
268.70342,71.54292,SN 2005B
168.87258,60.75153,SN 2005C

The command assumes that the input file is in the current working directory; you can also specify the full path to files that are not in the current directory. Be sure to leave the initlal '@' character, which tells curl that the contents of the file are to be uploaded.

This command can be easily modified to change the filename and search radius.  See the crossmatch API documentation for information on additional search parameters, file size and radius limits, changing the names of the ra and dec columns, etc.  You can change the data format to JSON or VOTABLE by modifying the URL to 'upload.json' or 'upload.votable'.

Other curl command options may also be useful (e.g., --compressed to allow the file to be compressed to speed the data transfer.) 

Python example

A similar approach can be used with other tools that allow uploading files in POST commands.  For example, here is Python 3 code using the requests module:

import requests
r = 0.000833			# radius in degrees
filename = 'sn2005.csv'
url = ''

r =, params=dict(radius=r), files=dict(file=open(filename,'rb')))
print(r.text, end='')	# print output without trailing newline