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
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.json?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.json
[
{
"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
// With Decorator
GET /panstarrs/dr1/mean.json
// With Accept Header
GET /panstarrs/dr1/mean
ACCEPT: application/json
// 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
- POST /api/v0.1/panstarrs/{release}/{catalog}/crossmatch/upload
Get crossmatch data for specified catalog
Search Pan-STARRS through crossmatch of an uploaded file
- Request Headers:
accept (string) –
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean.
release (required) – Panstarrs data release, DR1 or DR2
- Query Parameters:
result_format (string) – Format of results (CSV or JSON)
flatten_response (boolean) – Request responses to return as a list of lists rather than a list of objects.
format – Format of the response (json/csv/xml/votable)
delimiter – Delimiter used in csv response
raw (boolean) – Request all responses to be in raw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types.
include_info (boolean) – Request responses to include column info. If true, the response will include the info key within the return object with available column information.
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- POST /api/v0.1/panstarrs/{release}/{catalog}/crossmatch/upload.{result_format}
Get crossmatch data for specified catalog
Search Pan-STARRS through crossmatch of an uploaded file
- Request Headers:
accept (string) –
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean.
result_format (string, required) – Format of results (CSV or JSON)
release (required) – Panstarrs data release, DR1 or DR2
- Query Parameters:
flatten_response (boolean) – Request responses to return as a list of lists rather than a list of objects.
format – Format of the response (json/csv/xml/votable)
delimiter – Delimiter used in csv response
raw (boolean) – Request all responses to be in raw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types.
include_info (boolean) – Request responses to include column info. If true, the response will include the info key within the return object with available column information.
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- POST /api/v0.1/panstarrs/{release}/{catalog}/crossmatch/{result_format}
Get crossmatch data for specified catalog
Search Pan-STARRS through crossmatch of submitted targets
- Request Headers:
accept (string) –
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean
result_format (string, required) – Format of results (CSV or JSON)
release (required) – Panstarrs data release, DR1 or DR2
- Query Parameters:
flatten_response (boolean) – Request responses to return as a list of lists rather than a list of objects.
format – Format of the response (json/csv/xml/votable)
delimiter – Delimiter used in csv response
raw (boolean) – Request all responses to be in raw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types.
include_info (boolean) – Request responses to include column info. If true, the response will include the info key within the return object with available column information.
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- GET /api/v0.1/panstarrs/cone/
Get observations for specified target
Get observations for specified target
- Query Parameters:
ra (number, required) – Right Ascension
dec (number, required) – Declination
radius (number) – search radius to consider in degrees, default is 0.2 degrees.
result_format (string) – Desired result format
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- GET /api/v0.1/panstarrs/{release}/{catalog}/metadata
Get column metadata (name, type, description) for specified catalog
Return column metadata (name, type, description)
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean.
release (required) – Panstarrs data release, DR1 or DR2
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- GET /api/v0.1/panstarrs/{release}/{catalog}/metadata.json
Get column metadata (name, type, description) for specified catalog
Return column metadata (name, type, description)
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean.
release (required) – Panstarrs data release, DR1 or DR2
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- GET /api/v0.1/panstarrs/{release}/{catalog}/count.json
Get filtered data for specified catalog
Get filtered data for specified catalog
- Request Headers:
accept (string) –
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean
release (required) – Panstarrs data release, DR1 or DR2
- Query Parameters:
columns (array) – A list of column names to include
sort_by (array) – A list of columns to sort by
pagesize (integer) – The number of records to return per page
page (integer) – If using pagesize, the page number to return
ra –
dec –
radius (number) – Radius; must be between zero and 1.0 degrees
sr (number) – The radius for the cone search (alternative to radius)
flatten_response (boolean) – Request responses to return as a list of lists rather than a list of objects.
format – Format of the response (json/csv/xml/votable)
delimiter – Delimiter used in csv response
raw (boolean) – Request all responses to be in raw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types.
include_info (boolean) – Request responses to include column info. If true, the response will include the info key within the return object with available column information.
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- POST /api/v0.1/panstarrs/{release}/{catalog}/count.json
Get filtered data for specified catalog
Post method for search requests
- Request Headers:
accept (string) –
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean
release (required) – Panstarrs data release, DR1 or DR2
- Query Parameters:
flatten_response (boolean) – Request responses to return as a list of lists rather than a list of objects.
format – Format of the response (json/csv/xml/votable)
delimiter – Delimiter used in csv response
raw (boolean) – Request all responses to be in raw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types.
include_info (boolean) – Request responses to include column info. If true, the response will include the info key within the return object with available column information.
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- GET /api/v0.1/panstarrs/{release}/{catalog}.{file_type}
Get filtered data for specified catalog
Get filtered data for specified catalog
- Request Headers:
accept (string) –
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean
release (required) – Panstarrs data release, DR1 or DR2
- Query Parameters:
columns (array) – A list of column names to include
sort_by (array) – A list of columns to sort by
pagesize (integer) – The number of records to return per page
page (integer) – If using pagesize, the page number to return
ra –
dec –
radius (number) – Radius; must be between zero and 1.0 degrees
sr (number) – The radius for the cone search (alternative to radius)
flatten_response (boolean) – Request responses to return as a list of lists rather than a list of objects.
format – Format of the response (json/csv/xml/votable)
delimiter – Delimiter used in csv response
raw (boolean) – Request all responses to be in raw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types.
include_info (boolean) – Request responses to include column info. If true, the response will include the info key within the return object with available column information.
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- POST /api/v0.1/panstarrs/{release}/{catalog}.{file_type}
Get filtered data for specified catalog
Get filtered data for specified catalog
- Request Headers:
accept (string) –
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean
release (required) – Panstarrs data release, DR1 or DR2
- Query Parameters:
flatten_response (boolean) – Request responses to return as a list of lists rather than a list of objects.
format – Format of the response (json/csv/xml/votable)
delimiter – Delimiter used in csv response
raw (boolean) – Request all responses to be in raw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types.
include_info (boolean) – Request responses to include column info. If true, the response will include the info key within the return object with available column information.
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- GET /api/v0.1/panstarrs/{release}/{catalog}
Get filtered data for specified catalog
Get filtered data for specified catalog
- Request Headers:
accept (string) –
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean
release (required) – Panstarrs data release, DR1 or DR2
- Query Parameters:
columns (array) – A list of column names to include
sort_by (array) – A list of columns to sort by
pagesize (integer) – The number of records to return per page
page (integer) – If using pagesize, the page number to return
ra –
dec –
radius (number) – Radius; must be between zero and 1.0 degrees
sr (number) – The radius for the cone search (alternative to radius)
flatten_response (boolean) – Request responses to return as a list of lists rather than a list of objects.
format – Format of the response (json/csv/xml/votable)
delimiter – Delimiter used in csv response
raw (boolean) – Request all responses to be in raw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types.
include_info (boolean) – Request responses to include column info. If true, the response will include the info key within the return object with available column information.
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments
- POST /api/v0.1/panstarrs/{release}/{catalog}
Get filtered data for specified catalog
Get filtered data for specified catalog
- Request Headers:
accept (string) –
- Parameters:
catalog (string, required) – Panstarrs catalog, one of mean|stack|detection|forced_mean
release (required) – Panstarrs data release, DR1 or DR2
- Query Parameters:
flatten_response (boolean) – Request responses to return as a list of lists rather than a list of objects.
format – Format of the response (json/csv/xml/votable)
delimiter – Delimiter used in csv response
raw (boolean) – Request all responses to be in raw form. If false, the response will convert all items of long data type to a string. This is useful for languages with problems encoding long data types.
include_info (boolean) – Request responses to include column info. If true, the response will include the info key within the return object with available column information.
- Status Codes:
200 OK – Success
422 Unprocessable Entity – Unable to validate input arguments