##################### Hubble Source Catalog ##################### .. contents:: Table of Contents :depth: 3 ******************* Catalog Overview ******************* The HSC catalog API allows the ability to search the Hubble Source Catalog (versions 3 and 2). For additional information on the catalogs please visit the `HSC Data Archive Home Page`_. .. csv-table:: Catalog Tables and Additional Information :header: "Catalog", "Table/View", "Additional Information" "Summary, MagAper2", *SumMagAper2CatView*, `HSC SumMagAper2CatView Table Fields`_ "Summary, MagAuto", *SumMagAutoCatView*, `HSC SumMagAutoCatView Table Fields`_ "Detailed", *detailedCatalog*, `HSC Detailed Detection Table Fields`_ "Summary, Hubble Catalog of Variables", *HCVSummaryView*, `HCV Summary Table Fields`_ "Hubble Catalog of Variables", *HCVDetailedView*, `HCV Detailed Table Fields`_ "SWEEPS Proper Motions", *ProperMotionsView*, `HSC SWEEPS Field Proper Motion Table Fields`_ "SWEEPS Source Positions", *SourcePositionsView*, `HSC SWEEPS Field Source Positions Table Fields`_ .. _HSC SumMagAper2CatView Table Fields: https://catalogs.mast.stsci.edu/hsc/summary-fields.html .. _HSC SumMagAutoCatView Table Fields: https://catalogs.mast.stsci.edu/hsc/summary-fields.html .. _HSC Detailed Detection Table Fields: https://catalogs.mast.stsci.edu/hsc/detailed-fields.html .. _HCV Summary Table Fields: https://catalogs.mast.stsci.edu/hsc/hcv-summary-fields.html .. _HCV Detailed Table Fields: https://catalogs.mast.stsci.edu/hsc/hcv-fields.html .. _HSC SWEEPS Field Proper Motion Table Fields: https://catalogs.mast.stsci.edu/hsc/proper-motions-fields.html .. _HSC SWEEPS Field Source Positions Table Fields: https://catalogs.mast.stsci.edu/hsc/source-positions-fields.html .. _HSC Data Archive Home Page: https://catalogs.mast.stsci.edu/hsc/description.html ******************* Getting Started ******************* Quick Start =============== For more detailed information on using the API, continue below to :ref:`hsc-usage-label`. Example 1: HSCv3 MagAuto Summary Search ----------------------------------------- Search HSCv3 MagAuto Summary catalog at a point in the sky in a 10" cone, return entries in CSV form .. sourcecode:: http https://catalogs.mast.stsci.edu/api/v0.1/hsc/v3/summary/magauto.csv?ra=190.9167&dec=11.55261&radius=0.002777777777778 Click to try `Quick Start Example 1`_ .. _Quick Start Example 1: https://catalogs.mast.stsci.edu/api/v0.1/hsc/v3/summary/magauto.csv?ra=190.9167&dec=11.55261&radius=10 Example 2: HSC Summary VO Table with Column Selection ------------------------------------------------------ Search HSC Summary MagAper2 catalog at a point in the sky where numimages is greater than or equal to 2, return at most 10 entries in VO Table format, only include column MatchID .. sourcecode:: http https://catalogs.mast.stsci.edu/api/v0.1/hsc/v3/summary/magaper2.votable? ra=210.80227&dec=54.348950&radius=0.001 &numimages.gte=2f &pagesize=10 &columns=[MatchID] Click to try `Quick Start Example 2`_ .. _Quick Start Example 2: https://catalogs.mast.stsci.edu/api/v0.1/hsc/v3/summary/magaper2.votable? ra=210.80227&dec=54.348950&radius=0.001 &numimages.gte=2 &pagesize=10 &columns=[MatchID] Specify Output Columns ^^^^^^^^^^^^^^^^^^^^^^^^ .. sourcecode:: http https://catalogs.mast.stsci.edu/api/v0.1/hsc/v3/summary/magaper2? ra=210.802429&dec=54.348750&radius=0.001& numimages.gte=2& columns=[matchid,numimages,targetname,w2_f300w] 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/hsc/v3/summary/magaper2.csv?ra=210.802429&dec=54.348750&radius=0.001&nDetections.gte=1&pagesize=10&columns=[matchid,numimages,targetname,w2_f300w] .. _hsc-usage-label: ********** Usage ********** Access =========== The HSC 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 HSC Path https://catalogs.mast.stsci.edu/api/v0.1/hsc/ Selecting Catalogs ==================== The HSC API currently supports the querying of HSC V3 (version 3) and V2 (version 2). To access the different version of the HSC catalogs, indicate the version within the path: .. sourcecode:: HTTP :caption: Accessing V3 and V2 HSC Catalogs /hsc/v3/ /hsc/v2/ HSC V3 and V2 include the Summary and Detailed catalogs. Summary searches allows for the querying of Mag Types of MagAper2 and MagAuto. To access HSC V3/V2 Summary MagAper2 and MagAuto searches, use the following paths: .. sourcecode:: HTTP :caption: Summary MagAper2, MagAuto /hsc/v3/summary/magaper2 /hsc/v3/summary/magauto /hsc/v2/summary/magaper2 /hsc/v2/summary/magauto To access the HSC V3/V2 Detailed search, use the following path: .. sourcecode:: HTTP :caption: Detailed /hsc/v3/detailed /hsc/v2/detailed To access the HCV Summary and Detailed searches, use the following paths: .. sourcecode:: HTTP :caption: HCV Summary, Detailed /hsc/v3/hcvsummary /hsc/v3/hcv Searching HSC ===================== 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 **Example** Count for HSC Detailed Catalog .. sourcecode:: HTTP :caption: Count for Point of Sky Search Example /hsc/v3/detailed/count?ra=210.802429&dec=54.348750&radius=0.00833333 **Example** Count for HSC Summary MagAuto Catalog .. sourcecode:: HTTP :caption: Count for Point of Sky Search Example /hsc/v3/summary/magauto/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 HSC version supports the return of metadata. **Example** Receive metadata for HSC Detailed Catalog .. sourcecode:: HTTP :caption: Meta Data Request Example (HSC Detailed) /hsc/v3/detailed/metadata .. sourcecode:: json :caption: Meta Data Response Sample (HSC Detailed) [{ "name": "CatID", "type": "NUMBER", "description": null }, { "name": "MatchID", "type": "NUMBER", "description": null }, { "name": "MemID", "type": "NUMBER", "description": null }, ... }] 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. Currently, the Summary MagAper2 catalog is utilized for crossmatching. During the crossmatch, all null columns are removed. 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 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 degrees (~3 arcseconds), "The radius to crossmatch in degrees. Maximum of 0.000833333333333 degrees (~3 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 /hsc/v3/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_": 202.469575, "_dec_": 47.195258, "_searchID_": 0, "MatchID": 49376116, "distanceArcMin": 0.003123671714663302, "MatchRA": 202.4696116843927, "MatchDec": 47.19530370565952, "DSigma": 125.32767775370176, "AbsCorr": "Y", "NumFilters": 7, "NumVisits": 5, "NumImages": 8, "StartTime": "1995-01-24 21:10:17.090000", "StopTime": "2014-09-11 07:29:08.513000", "StartMJD": 49741.88214220852, "StopMJD": 56911.31190406252, "TargetName": "SN-1994I-COMPANION", "CI": 2.981806137592615, "CI_Sigma": 0.43429232229113296, "KronRadius": 0.258125000372529, "KronRadius_Sigma": 0.16302798808614785, "Extinction": 0.03598929941654205, "W3_F275W": 20.301000595092773, "W3_F275W_MAD": 0, "W3_F275W_N": 1, "W2_F336W": null, "W2_F336W_MAD": null, "W2_F336W_N": null, "W3_F336W": 19.612600326538086, "W3_F336W_MAD": 0, "W3_F336W_N": 1, "W2_F450W": null, "W2_F450W_MAD": null, "W2_F450W_N": null, "W2_F502N": 16.291391372680664, "W2_F502N_MAD": 0, "W2_F502N_N": 1, "W2_F547M": 16.8782901763916, "W2_F547M_MAD": 0, "W2_F547M_N": 1, "W2_F656N": 15.643889427185059, "W2_F656N_MAD": 0, "W2_F656N_N": 1, "W3_F673N": 17.63564968109131, "W3_F673N_MAD": 0.011050224304199219, "W3_F673N_N": 2, "W2_F675W": null, "W2_F675W_MAD": null, "W2_F675W_N": null, "W3_F689M": 17.59760093688965, "W3_F689M_MAD": 0, "W3_F689M_N": 1, "W2_F814W": null, "W2_F814W_MAD": null, "W2_F814W_N": null, "W3_F110W": null, "W3_F110W_MAD": null, "W3_F110W_N": null, "W3_F128N": null, "W3_F128N_MAD": null, "W3_F128N_N": null }, ... ]} 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 degrees (~3 arcseconds), "The radius to crossmatch in degrees. Maximum of 0.00083333333 degrees (~3 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 /hsc/v3/crossmatch/upload file=example1.csv header=True resolve=True radius=0.0008 ra_name=ra dec_name=dec target_name=target .. 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 /hsc/v3/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 HSC 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. The spatial search also accepts the query level parameter, ``nd``. .. csv-table:: Advanced Spatial Search Query Level ``nd`` Values :header: "Value", "Description", "Notes" 0, "All detected sources", "Default" 1, "Detections and filter-based non-detections", "" 2, "Detections, filter-based non-detections, and visit-based non-detections", "" 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: HSCv3 MagAper2 JSON Format GET // With Decorator GET /hsc/v3/summary/magaper2.json // With Accept Header GET /hsc/v3/summary/magaper2 ACCEPT: application/json Selecting Columns ^^^^^^^^^^^^^^^^^^^^^^ View :ref:`selecting-columns-label` .. sourcecode:: HTTP :caption: HSCv3 Summary MagAper2 MatchID, numimages columns GET //hsc/v3/summary/magaper2?columns=MatchID&columns=numimages // note case insensitivity /hsc/v3/summary/magauto?columns=MATCHID&columns=NUMIMAGES /hsc/v3/summary/magaper2?columns=["MatchID","numimages"] /hsc/v3/summary/magaper2?columns=[MatchID,numimages] .. sourcecode:: HTTP :caption: HSCv3 Summary MagAper2 objName, nDetections columns POST /hsc/v3/summary/magaper2 columns=MatchID columns=numimages /hsc/v3/summary/magaper2 columns=[MatchID,numimages] Column Filtering ^^^^^^^^^^^^^^^^^^^^^ View :ref:`column-filtering-label` .. sourcecode:: HTTP :caption: HSCv3 Summary MagAper2 numimages greater than or equal to 1 POST /hsc/v3/summary/magaper2 numimages.gte=1 .. sourcecode:: HTTP :caption: HSCv3 Summary MagAper2 numimages equal to 2 POST /hsc/v3/summary/magaper2 numimages=2 Sorting ^^^^^^^^^^^^^ View :ref:`sorting-label` .. sourcecode:: HTTP :caption: HSCv3 Summary MagAper2 Sort By nDetections descending (DESC) and distance ascending (ASC) POST /hsc/v3/summary/magaper2 sort_by=numimages.desc sort_by=distance.ASC Paging ^^^^^^^^^^^^^ View :ref:`paging-label` .. sourcecode:: HTTP :caption: HSCv3 Summary MagAper2 POST Second Page of Page Size of 100 /hsc/v3/summary/magaper2 pagesize=100 page=2 ************************** HSC API Services ************************** .. openapi:httpdomain:: _static/swagger/hsc_openapi.json