Pan-STARRS Catalog

Catalog Overview

The Pan-STARRs catalog API allows the ability to search the Pan-STARRS catalogs. For additional information on the catalogs please visit the Pan-STARRS Data Archive Home Page.

Catalog Tables and Additional Information

Catalog

Table/View

Additional Information

Mean

MeanObjectView

PS1 MeanObjectView Table Fields

Stack Object

StackObjectView

PS1 StackObjectView Table Fields

Detection

Detection

PS1 Detection Table Fields (DR2 Only)

Forced Mean

ForcedMeanObjectView

PS1 ForcedMeanObjectView Table Fields

The Mean catalog uses the MeanObjectView table and the Stack Object catalog uses the StackObjectView table. For additional information on these tables please visit PS1 MeanObjectView Table Fields and PS1 StackObjectView Table Fields pages.

How to retrieve and use PS1 data offers helpful information on the use of the API, including example Python Jupyter notebooks.

Getting Started

Quick Start

For more detailed information on using the API, continue below to Usage.

Example 1: DR 1 Mean CSV with Page Size

Search DR 1 (data release 1) mean catalog at a point in the sky, return at most 10 entries in CSV format

https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/mean.csv?
ra=210.802429&dec=54.348750&radius=0.00833333&
pagesize=10

Click to try Quick Start Example 1

Example 2: DR 1 Stack VO Table with Column Selection

Search DR 1 stack catalog at a point in the sky where nDetections is greater than or equal to 2, return at most 10 entries in VO Table format, only include column ObjName

https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/mean.votable?
ra=210.802429&dec=54.348750&radius=0.00833333
&nDetections.gte=2
&pagesize=10
&columns=[ObjName]

Click to try Quick Start Example 2

Comparison of New API to Previous Version

Scenario: Search Mean Objects Table

Search ra=210.802429, dec=54.348750 (M101) with a radius=0.5 arcmin for objects with nDetections => 1. Return at most 50001 rows of output in CSV format with positions in decimal degrees. Get default columns.

Minimal Example
New API
https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/mean?
ra=210.802429&dec=54.348750&radius=0.00833333&
nDetections.gte=1&
pagesize=5001&
format=csv

Click to try New API Minimal Example

Note .5 arcminutes equals .008333333 degrees, and “dr1” is “Data Release 1”

Previous API
http://archive.stsci.edu/panstarrs/search.php?action=Search&
ra=210.802429&dec=54.348750&radius=0.5&
nDetections=>1&
max_records=50001&
outputformat=CSV&
coordformat=dec

Click to try Old API Minimal Example

Comparing API Calls

Previous

New

New API Notes

ra

ra

dec

dec

radius

radius

Must be in degrees. 0.5 arcminuts = 0.008333333 degrees

nDetections=>

nDetections.gte

Greater than or equal decorator

max_records

pagesize

To get the next page, increase the page parameter from the default of 1

outputformat=CSV

format=CSV

Indicate output via format parameter, .csv decorator, or Accept header

coordformat=dec

None

Only supports decimal degrees output at this time.
Specify Output Columns
New API
https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/mean?
ra=210.802429&dec=54.348750&radius=0.00833333&
nDetections.gte=1&
columns=[objid,ramean,decmean,rameanerr,decmeanerr,ndetections,ng,nr,ni,nz,ny,gmeanpsfmag,rmeanpsfmag,imeanpsfmag]
pagesize=5001&
format=csv

Click to try New API Specify Columns Example

Previous API
http://archive.stsci.edu/panstarrs/search.php?action=Search&
ra=210.802429&dec=54.348750&radius=0.5&
equinox=J2000&
selectedColumnsCsv=objid,ramean,decmean,rameanerr,decmeanerr,ndetections,ng,nr,ni,nz,ny,gmeanpsfmag,rmeanpsfmag,imeanpsfmag&
nDetections=>1&
max_records=50001&
outputformat=CSV&
coordformat=dec

Click to try Old API Specify Columns Example

Comparing API Calls (Selecting Columns)

Previous

New

New API Notes

selectedColumnsCsv

columns

Multiple columns parameters or a list of column names
Minimal Example Using the VO Interface

Search the same position and radius with VO cone search parameters (ra, dec, sr) and VO output. Note that SR is search radius in degrees, not arcminutes, so its value is different from the above search

New API
https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/stack.votable?
ra=210.802429&dec=54.348750&radius=0.0083333&
nDetections.gte=1

https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/stack.votable?
ra=210.802429&dec=54.348750&sr=0.0083333&
nDetections.gte=1

Note VO Table format requested by using format decorator in example

Click to try New API VO Example

Previous API
http://archive.stsci.edu/panstarrs/search.php?
ra=210.802429&dec=54.348750&sr=0.0083333&
nDetections=>1

Click to try Old API VO Example

Comparing API Calls (VO)

Previous

New

New API Notes

default format

.votable

Indicate output via format parameter, .votable decorator, or Accept header

sr

radius or sr

Radius may be submitted via radius or sr parameters. Radius must be in decimals

Scenario: Search Stack Objects Table

New API
https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/stack.json?
ra=210.802429&dec=54.348750&radius=0.00833333&
pagesize=50001

Note JSON format requested by using format decorator in example

Click to try New API Stack Objects Example

Previous API
http://archive.stsci.edu/panstarrs/stackobject/search.php?action=Search&
outputformat=JSON&
ra=210.802429&dec=54.348750&radius=0.5&
coordformat=dec&
max_records=50001&

Click to try Old API Stack Objects Example

Usage

Access

The Pan-STARRS API can be accessed using GET or POST requests. POST is recommended due to the potentially large request size.

Note Currently, the /metadata endpoint only supports GET

Note If duplicate parameters are present in the query string and request body of a POST, the request body will override behavior

Base Pan-STARRS Path
https://catalogs.mast.stsci.edu/api/v0.1/panstarrs

Selecting Catalogs

The Pan-STARRS API currently supports the querying of the DR1 (Data Release 1) and DR2 (Data Release 2) Catalogs.

Available catalogs also include mean and stack object searches.

To access DR 1 mean and stack object searches, use the following paths:

DR 1 Mean, and Stack
/panstarrs/dr1/mean
/panstarrs/dr1/stack

To access DR 2 mean and stack object searches, use the following paths:

DR 2 Mean, Stack, and Detection
/panstarrs/dr2/mean
/panstarrs/dr2/stack
/panstarrs/dr2/detection
/panstarrs/dr2/forced_mean

To access the most recent data release (currently DR 2) mean and stack object searches, use the following paths:

Most Recent Data Release (DR 2) Mean, Stack, Detection and Forced Mean
/panstarrs/mean
/panstarrs/stack
/panstarrs/detection
/panstarrs/forced_mean

Searching Pan-STARRS

Count

Counts may be returned based on a given query (search query creation details below)

To access counts, append the /count path to a given catalog mean or stack search search query

Example Count for DR1 stack

Count for Point of Sky Search Example
/panstarrs/dr1/stack/count?ra=210.802429&dec=54.348750&radius=0.00833333

Meta Data

The /metadata path provides additional information of available columns for a given catalog. The additional information includes: column name, column data type, and column description. Each Pan-STARRS catalog supports the return of metadata.

Example Receive metadata for DR1 mean

Meta Data Request Example (DR 1 Mean)
/panstarrs/dr1/mean/metadata
Meta Data Response Sample (DR 1 Mean)
[
    {
        "name": "objName",
        "type": "STRING",
        "description": "IAU name for this object."
    },
    {
        "name": "objPSOName",
        "type": "STRING",
        "description": "Alternate name for this object."
    },...
]

Crossmatch

The /crossmatch and /crossmatch/upload paths provide crossmatch functionality, returning matching database elements. The returned results cannot be paged, ordered, column-filtered or column-selected.

Only POST method is supported.

  • /crossmatch/upload : Upload a CSV file of coordinates or target names

  • /crossmatch : Post a list of coordinates or target names

Note Support is now expanded to support all DR1 (mean, stack) and DR2 (mean, stack, detection and forced mean) catalogs.

For more advanced functionality (column selection, column filtering, paging and ordering) and additional table support (stack, forced-mean, detections), other interfaces should be used, such as the UI interface, VO Cone Search, CASJobs, or using the API to loop through a list of coordinates (such as the use of Python) as shown in Python notebook examples

Resolver

Provided target names or coordinates may be resolved to verify provided information. If provided, the target column will be used for resolution, then the RA and Dec column. Resolving a large list or file will greatly increase the return time for the API request.

If a target or coordinate cannot be resolved, the item will be omitted from the crossmatch. If none of the provided targets or coordinates can be resolved, an error will return with a notification.

Crossmatch JSON

A JSON list may be submitted for crossmatching through the /crossmatch/ path.

Valid JSON

The JSON submitted should consist of an array of dictionaries/objects, each containing keys for ra, dec, and target (if resolving target names). The length of the JSON list is restricted to 5,000 items.

JSON Request Parameters

The crossmatch request should contain parameters indicating the field names of the submitted JSON list.

Simple Crossmatch Request Parameters

Parameter

Default

Description

targets

Required

The targets array of dictionaries/objects containing the target information.

resolve

False

Whether to resolve the file coordinates/targets.

radius

0.000833 arcminutes (~3 arcseconds)

The radius to crossmatch in arcminutes. Maximum of 0.001389 arcminutes (~5 arcseconds)

ra_name

ra

Key name for field containing RA coordinates.

dec_name

dec

Key name for field containing Dec coordinates.

target_name

target

Key name for field containing target names.
Crossmatch Input Dictionary/Object

Field

Description

ra

Field containing RA coordinates. Must be in decimals if not resolving.

dec

Field containing Dec coordinates. Must be in decimals if not resolving.

target

Field containing target names.
Example
Sample Request
// POST
/panstarrs/dr2/mean/crossmatch
targets=[{
     "ra": "37.68021",
     "dec": "-2.93883",
     "target": "SN 2005A"
    },{
     "ra": "268.70342",
     "dec": "71.54292",
     "target": "SN 2005B"
    },{
     "ra": "168.87258",
     "dec": "60.75153",
     "target": "SN 2005C"
    },{
     "ra": "111.73900",
     "dec": "20.38150",
     "target": "SN 2005D"
    }]
resolve=True
radius=0.0008
ra_name=ra
dec_name=dec
target_name=target
Example JSON Response
{
    "data": [
        {
            "_ra_": 180.84963,
            "_dec_": 35.32583,
            "_searchID_": 64,
            "MatchID": 150391808496241531,
            "MatchRA": 180.84963382,
            "MatchDEC": 35.32582027,
            "dstArcSec": 0.0006130180044370951,
            "objName": "PSO J180.8496+35.3258",
            "objAltName1": "-999",
            "objAltName2": "-999",
            "objAltName3": "-999",
            "uniquePspsOBid": 3607691000048332
        }
    ]
}
Crossmatch Upload

A CSV file may be uploaded for crossmatching through the /crossmatch/upload path.

Valid CSV

The CSV submitted must be comma-delimited file ending in .csv with an optional text/csv content-type. The file may contain a header describing the given columns. Without a header row, the request must also include the positional request parameters describing the CSV file. The length of the CSV file is limited by 5,000 rows.

Request Parameters

The crossmatch request should contain parameters indicating the information provided within the uploaded CSV file. These parameters indicate the presence of a header (header), the name of the columns (if a header is provided) and/or the position of the given column types (if no header).

Simple Crossmatch Request Parameters

Parameter

Default

Description

file

Required

The file to be uploaded in the POST request. 1 file is supported per call.

header

True

If the file has a CSV header. If False, column positions must be provided

resolve

False

Whether to resolve the file coordinates/targets.

radius

0.000833 arcminutes (~3 arcseconds)

The radius to crossmatch in arcminutes. Maximum of 0.001389 arcminutes (~5 arcseconds)

ra_name

ra

Column header name for the column containing RA coordinates..

dec_name

dec

Column header name for the column containing Dec coordinates.

target_name

target

Column header name for the column containing target names.

ra_pos

The column position (beginning at 0) that indicates the RA column.

dec_pos

The column position (beginning at 0) that indicates the Dec column.

target_pos

The column position (beginning at 0) that indicates the Target column.
Crossmatch Input Columns

Column

Description

ra

Column containing RA coordinates. Must be in decimals if not resolving.

dec

Column containing Dec coordinates. Must be in decimals if not resolving.

target

Column containing target names.
Examples
Example 1 Sample File example1.csv
ra, dec, target
37.68021,-2.93883,SN 2005A
268.70342,71.54292,SN 2005B
168.87258,60.75153,SN 2005C
Example 1 Sample Request
// POST
/panstarrs/dr2/mean/crossmatch/upload
file=example1.csv
header=True
resolve=True
radius=0.0008
ra_name=ra
dec_name=dec
target_name=target
Example 1 Sample Request via cURL and return CSV
// POST
curl -X POST \
https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/mean/crossmatch/upload.csv \
-F resolve=false \
-F radius=0.000833 \
-F 'file=@example1.csv'
Example 2 Sample File example2.csv
37.68021,-2.93883
268.70342,71.54292
168.87258,60.75153
Example 1 Sample Request
// POST
/panstarrs/dr2/mean/crossmatch/upload
file=example2.csv
header=False
resolve=False
radius=0.0008
ra_pos=0
dec_pos=1

Searching By RA, Dec, and Radius

The Pan-STARRS catalog may be searched based on entered RA, Dec and Radius parameters.

Radius may also be submitted via the parameter sr. All following radius restrictions also apply to sr.

RA and Dec must be in decimal values. Radius must be in degrees.

To perform the cone search RA, Dec and radius are required.

General Searching

Please read documentation for more detailed general search guidelines for our catalog services. Using MAST Catalogs

Formats

View Encoding Formats

DR 1 Mean JSON Format GET
// Default
GET /panstarrs/dr1/mean

// With Decorator
GET /panstarrs/dr1/mean.json

// With Parameter
GET /panstarrs/dr1/mean/format=json

// With Accept Header
GET /panstarrs/dr1/mean
ACCEPT: application/json
DR 1 Mean JSON Format GET
// Default
POST /panstarrs/dr1/mean

// With Decorator
POST /panstarrs/dr1/mean.json

// With Accept Header
POST /panstarrs/dr1/mean
ACCEPT: application/json

// With Parameter
POST /panstarrs/dr1/mean
format=json
Selecting Columns

View Selecting Columns

DR 1 Mean objName, nDetections columns GET
/panstarrs/dr1/mean?columns=objName&columns=nDetections
// note case insensitivity
/panstarrs/dr1/mean?columns=OBJNAME&columns=NDETECTIONS

/panstarrs/dr1/mean?columns=["objName","nDetections"]
/panstarrs/dr1/mean?columns=[objName,nDetections]
DR 1 Mean objName, nDetections columns POST
/panstarrs/dr1/mean
columns=objName
columns=nDetections

/panstarrs/dr1/mean
columns=[objName,nDetections]
Column Filtering

View Column Filtering

DR 1 Mean nDetections greater than or equal to 1 POST
/panstarrs/dr1/mean
nDetections.gte=1
DR 1 Mean nDetections equal to 2 POST
/panstarrs/dr1/mean
nDetections=2
Sorting

View Sorting

DR 1 Mean Sort By nDetections descending (DESC) and distance ascending (ASC) POST
/panstarrs/dr1/mean
sort_by=nDetections.desc
sort_by=distance.ASC
Paging

View Paging

DR 1 Mean Sort By nDetections DESC and distance ASC POST Second Page of Page Size of 100
/panstarrs/dr1/mean
pagesize=100
page=2

Pan-STARRS API Services

GET /panstarrs/cone/?

Perform a cone search

Parameters:

  • ra (string) – The RA to cone search against

  • dec (string) – The DEC to cone search against

  • radius (float) – The Radius for the cone search

GET /panstarrs/(mean|stack|detection|forced_mean)/metadata.*/?

Return column metadata (name, type, description)

GET /panstarrs/(mean|stack|detection|forced_mean).*/?

Search for filtered Pan-STARRS results and return count if specified (/count)

Parameters:

  • ra (string) – The RA to cone search against

  • dec (string) – The DEC to cone search against

  • radius (float) – The Radius for the cone search

  • sr (float) – The Radius for the cone search (alternative to radius)

  • columns (string) – A list of column names to include

  • sort_by (string) – A list of columns to sort by

GET /panstarrs/(mean|stack|detection|forced_mean)/count.*/?

Search for filtered Pan-STARRS results and return count if specified (/count)

Parameters:

  • ra (string) – The RA to cone search against

  • dec (string) – The DEC to cone search against

  • radius (float) – The Radius for the cone search

  • sr (float) – The Radius for the cone search (alternative to radius)

  • columns (string) – A list of column names to include

  • sort_by (string) – A list of columns to sort by

POST /panstarrs/(mean|stack|detection|forced_mean)/crossmatch/upload.*/?

Search Pan-STARRS through crossmatch of an uploaded file

Parameters:

  • file (file) – file to upload

  • header (boolean) – header included in file

  • ra_name (string) – ra column name in header

  • ra_pos (int) – ra column position

  • dec_name (string) – dec column name in header

  • dec_pos (int) – dec column position

  • target_name (string) – target column name in header

  • target_pos (int) – target column position

  • radius (float) – radius value for crossmatch

  • resolve (boolean) – resolve passed targets/coordinates

Return:

DB result of crossmatch

Multiple radii will not be supported in in stead multiple calls should be done per each

POST /panstarrs/(mean|stack|detection|forced_mean)/crossmatch.*/?

Search Pan-STARRS through crossmatch of submitted targets

Parameters:

  • targets (array) – crossmatch targets containing coordinates and targets

  • ra_name (string) – ra key name in dict

  • dec_name (string) – dec key name in dict

  • target_name (string) – target key name in dict

  • radius (float) – radius value for crossmatch

  • resolve (boolean) – resolve passed targets/coordinates

Return:

DB result of crossmatch