##################### Pan-STARRS Catalog ##################### .. contents:: Table of Contents :depth: 3 ******************* 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`_. .. csv-table:: Catalog Tables and Additional Information :header: "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. .. _Pan-STARRS Data Archive Home Page: https://outerspace.stsci.edu/display/PANSTARRS/Pan-STARRS1+data+archive+home+page .. _PS1 MeanObjectView Table Fields: https://outerspace.stsci.edu/display/PANSTARRS/PS1+MeanObjectView+table+fields .. _PS1 StackObjectView Table Fields: https://outerspace.stsci.edu/display/PANSTARRS/PS1+StackObjectView+table+fields .. _PS1 Detection Table Fields: https://outerspace.stsci.edu/display/PANSTARRS/PS1+Detection+table+fields .. _PS1 ForcedMeanObjectView Table Fields: https://outerspace.stsci.edu/display/PANSTARRS/PS1+ForcedMeanObjectView+table+fields `How to retrieve and use PS1 data`_ offers helpful information on the use of the API, including example `Python Jupyter notebooks`_. .. _How to retrieve and use PS1 data: https://outerspace.stsci.edu/display/PANSTARRS/How+to+retrieve+and+use+PS1+data .. _Python Jupyter notebooks: http://ps1images.stsci.edu/ps1_dr2_api.html ******************* Getting Started ******************* Quick Start =============== For more detailed information on using the API, continue below to :ref:`ps-usage-label`. 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 .. sourcecode:: none 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`_ .. _Quick Start Example 1: https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/mean.csv? ra=210.802429&dec=54.348750&radius=0.00833333& pagesize=10 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 .. sourcecode:: none 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`_ .. _Quick Start Example 2: https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/mean.votable? ra=210.802429&dec=54.348750&radius=0.00833333 &nDetections.lte=1 &pagesize=10 &columns=[ObjName] 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 """"""""""""""" .. sourcecode:: http 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" .. _New API Minimal Example: 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 Previous API """""""""""""""""" .. sourcecode:: http 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`_ .. _Old API Minimal Example: http:// archive.stsci.edu/panstarrs/search.php?action=Search&ra=210.802429&dec=54.348750&radius=0.5&max_records=50001& outputformat=CSV&coordformat=dec&nDetections=>1 .. csv-table:: Comparing API Calls :header: "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 """""""""""""""""" .. sourcecode:: http 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`_ .. _New API Specify Columns Example: https://catalogs.mast.stsci.edu/ api/v0.1/panstarrs/dr1/mean.csv?ra=210.802429&dec=54.348750&radius=0.00833333&nDetections.gte=1&pagesize=10&columns=[objid,ramean,decmean,rameanerr,decmeanerr,ndetections,ng,nr,ni,nz,ny,gmeanpsfmag,rmeanpsfmag,imeanpsfmag] Previous API """""""""""""""""" .. sourcecode:: http 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`_ .. _Old API Specify Columns Example: http://archive.stsci.edu/panstarrs/search.php?action=Search &ra=210.802429&dec=54.348750&radius=0.5&equinox=J2000&outputformat=CSV&coordformat=dec&max_records=50001& selectedColumnsCsv=objid,ramean,decmean,rameanerr,decmeanerr,ndetections,ng,nr,ni,nz,ny,gmeanpsfmag,rmeanpsfmag, imeanpsfmag&nDetections=>1 .. csv-table:: Comparing API Calls (Selecting Columns) :header: "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 """""""""""""""""" .. sourcecode:: http https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/stack.votable? ra=210.802429&dec=54.348750&radius=0.0083333& nDetections.gte=1 .. sourcecode:: http 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`_ .. _New API VO Example: https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/stack.votable?ra=210.802429&dec=54.348750&radius=0.0083333&nDetections.gte=1 Previous API """""""""""""""""" .. sourcecode:: http 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`_ .. _Old API VO Example: http://archive.stsci.edu/panstarrs/search.php?ra=210.802429&dec=54.348750&sr=0.0083333&nDetections=>1 .. csv-table:: Comparing API Calls (VO) :header: "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 ^^^^^^^^^^^^ .. sourcecode:: http 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`_ .. _New API Stack Objects Example: https://catalogs.mast.stsci.edu/api/v0.1/panstarrs/dr1/stack.json?ra=210.802429&dec=54.348750&radius=0.00833333&pagesize=10 Previous API ^^^^^^^^^^^^^ .. sourcecode:: http 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`_ .. _Old API Stack Objects Example: http://archive.stsci.edu/panstarrs/stackobject/search.php?action=Search&ra=210.802429&dec=54.348750&radius=0.5&max_records=50001&outputformat=JSON&coordformat=dec .. _ps-usage-label: ********** 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 .. sourcecode:: HTTP :caption: 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: .. sourcecode:: HTTP :caption: DR 1 Mean, and Stack /panstarrs/dr1/mean /panstarrs/dr1/stack To access DR 2 mean and stack object searches, use the following paths: .. sourcecode:: HTTP :caption: DR 2 Mean, Stack, and Detection /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 .. sourcecode:: HTTP :caption: Count for Point of Sky Search Example /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 .. sourcecode:: HTTP :caption: Meta Data Request Example (DR 1 Mean) /panstarrs/dr1/mean/metadata.json .. sourcecode:: json :caption: 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`_ .. _UI interface: https://catalogs.mast.stsci.edu/ .. _VO Cone Search: http://gsss.stsci.edu/Software/WebServices.htm .. _CASJobs: http://mastweb.stsci.edu/ps1casjobs .. _Python notebook examples: http://ps1images.stsci.edu/ps1_dr2_api.html 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. .. csv-table:: Simple Crossmatch Request Parameters :header: 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." .. csv-table:: Crossmatch Input Dictionary/Object :header: 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 """""""""""" .. sourcecode:: http :caption: 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 .. sourcecode:: json :caption: 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). .. csv-table:: Simple Crossmatch Request Parameters :header: 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." .. csv-table:: Crossmatch Input Columns :header: 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 """""""""""" .. sourcecode:: csv :caption: 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 .. sourcecode:: http :caption: 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 .. sourcecode:: http :caption: 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' .. sourcecode:: csv :caption: Example 2 Sample File example2.csv 37.68021,-2.93883 268.70342,71.54292 168.87258,60.75153 .. sourcecode:: http :caption: 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. :doc:`general_catalog_service` Formats ^^^^^^^^^^^^^ View :ref:`encoding-formats-label` .. sourcecode:: HTTP :caption: DR 1 Mean JSON Format GET // With Decorator GET /panstarrs/dr1/mean.json // With Accept Header GET /panstarrs/dr1/mean ACCEPT: application/json .. sourcecode:: HTTP :caption: DR 1 Mean JSON Format POST // 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 :ref:`selecting-columns-label` .. sourcecode:: HTTP :caption: 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] .. sourcecode:: HTTP :caption: DR 1 Mean objName, nDetections columns POST /panstarrs/dr1/mean columns=objName columns=nDetections /panstarrs/dr1/mean columns=[objName,nDetections] Column Filtering ^^^^^^^^^^^^^^^^^^^^^ View :ref:`column-filtering-label` .. sourcecode:: HTTP :caption: DR 1 Mean nDetections greater than or equal to 1 POST /panstarrs/dr1/mean nDetections.gte=1 .. sourcecode:: HTTP :caption: DR 1 Mean nDetections equal to 2 POST /panstarrs/dr1/mean nDetections=2 Sorting ^^^^^^^^^^^^^ View :ref:`sorting-label` .. sourcecode:: HTTP :caption: 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 :ref:`paging-label` .. sourcecode:: HTTP :caption: 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 ************************** .. openapi:httpdomain:: _static/swagger/panstarrs_openapi.json