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 |
Table/View |
Additional Information |
---|---|---|
Mean |
MeanObjectView |
|
Stack Object |
StackObjectView |
|
Detection |
Detection |
PS1 Detection Table Fields (DR2 Only) |
Forced Mean |
ForcedMeanObjectView |
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
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 |
outputformat=CSV |
format=CSV |
Indicate output via |
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
Previous |
New |
New API Notes |
---|---|---|
selectedColumnsCsv |
columns |
Multiple |
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
Previous |
New |
New API Notes |
---|---|---|
default format |
.votable |
Indicate output via |
sr |
|
Radius may be submitted via |
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
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:
/panstarrs/dr1/mean
/panstarrs/dr1/stack
To access DR 2 mean and stack object searches, use the following paths:
/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:
/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
/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
/panstarrs/dr1/mean/metadata
[
{
"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.
Parameter |
Default |
Description |
---|---|---|
|
Required |
The targets array of dictionaries/objects containing the target information. |
|
|
Whether to resolve the file coordinates/targets. |
|
0.000833 arcminutes (~3 arcseconds) |
The radius to crossmatch in arcminutes. Maximum of 0.001389 arcminutes (~5 arcseconds) |
|
ra |
Key name for field containing RA coordinates. |
|
dec |
Key name for field containing Dec coordinates. |
|
target |
Key name for field containing target names. |
Field |
Description |
---|---|
|
Field containing RA coordinates. Must be in decimals if not resolving. |
|
Field containing Dec coordinates. Must be in decimals if not resolving. |
|
Field containing target names. |
Example¶
// 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
{
"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).
Parameter |
Default |
Description |
---|---|---|
|
Required |
The file to be uploaded in the POST request. 1 file is supported per call. |
|
|
If the file has a CSV header. If False, column positions must be provided |
|
|
Whether to resolve the file coordinates/targets. |
|
0.000833 arcminutes (~3 arcseconds) |
The radius to crossmatch in arcminutes. Maximum of 0.001389 arcminutes (~5 arcseconds) |
|
ra |
Column header name for the column containing RA coordinates.. |
|
dec |
Column header name for the column containing Dec coordinates. |
|
target |
Column header name for the column containing target names. |
|
The column position (beginning at 0) that indicates the RA column. |
|
|
The column position (beginning at 0) that indicates the Dec column. |
|
|
The column position (beginning at 0) that indicates the Target column. |
Column |
Description |
---|---|
|
Column containing RA coordinates. Must be in decimals if not resolving. |
|
Column containing Dec coordinates. Must be in decimals if not resolving. |
|
Column containing target names. |
Examples¶
ra, dec, target
37.68021,-2.93883,SN 2005A
268.70342,71.54292,SN 2005B
168.87258,60.75153,SN 2005C
// 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
// 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'
37.68021,-2.93883
268.70342,71.54292
168.87258,60.75153
// 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
// 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
// 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
/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]
/panstarrs/dr1/mean
columns=objName
columns=nDetections
/panstarrs/dr1/mean
columns=[objName,nDetections]
Column Filtering¶
View Column Filtering
/panstarrs/dr1/mean
nDetections.gte=1
/panstarrs/dr1/mean
nDetections=2
Sorting¶
View Sorting
/panstarrs/dr1/mean
sort_by=nDetections.desc
sort_by=distance.ASC
Paging¶
View Paging
/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