Hubble Source Catalog

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.

Catalog Tables and Additional Information
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
SWEEPS Proper Motions ProperMotionsView HSC SWEEPS Field Proper Motion Table Fields
SWEEPS Source Positions SourcePositionsView HSC SWEEPS Field Source Positions Table Fields

Getting Started

Quick Start

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

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

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

Specify Output Columns
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

Usage

Access

The HSC API can be accessed using GET or POST requests. POST is recommended due to the potential 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 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:

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:

Summary MagAper2 and 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:

Detailed
/hsc/v3/detailed
/hsc/v2/detailed

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

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

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

Meta Data Request Example (HSC Detailed)
/hsc/v3/detailed/metadata
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.

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.

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 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.
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
/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
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).

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 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.
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
/hsc/v3/crossmatch/upload
file=example1.csv
header=True
resolve=True
radius=0.0008
ra_name=ra
dec_name=dec
target_name=target
Example 2 Sample File example2.csv
37.68021,-2.93883
268.70342,71.54292
168.87258,60.75153
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.

Advanced Spatial Search Query Level nd Values
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. Using MAST Catalogs

Formats

View Encoding Formats

HSCv3 MagAper2 JSON Format GET
// Default
GET /hsc/v3/summary/magaper2

// With Decorator
GET /hsc/v3/summary/magaper2.json

// With Parameter
GET /hsc/v3/summary/magaper2/format=json

// With Accept Header
GET /hsc/v3/summary/magaper2
ACCEPT: application/json
Selecting Columns

View Selecting Columns

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]
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 Column Filtering

HSCv3 Summary MagAper2 numimages greater than or equal to 1 POST
/hsc/v3/summary/magaper2
numimages.gte=1
HSCv3 Summary MagAper2 numimages equal to 2 POST
/hsc/v3/summary/magaper2
numimages=2
Sorting

View Sorting

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 Paging

HSCv3 Summary MagAper2 POST Second Page of Page Size of 100
/hsc/v3/summary/magaper2
pagesize=100
page=2

HSC API Services

GET /hsc/(summary)/(magaper2|magauto)/metadata.*/?

Return column metadata (name, type, description)

Parameters:
  • catalog (string) – Summary/Detailed/Proper Motions/Source Positions catalog
  • mag (string) – MagAper2 or MagAuto (Summary-only)
GET /hsc/(detailed|propermotions|sourcepositions)/metadata.*/?

Return column metadata (name, type, description)

Parameters:
  • catalog (string) – Summary/Detailed/Proper Motions/Source Positions catalog
  • mag (string) – MagAper2 or MagAuto (Summary-only)
GET /hsc/(summary)/(magaper2|magauto).*/?

Search for filtered HSC results and return count if specified (/count)

Parameters:
  • catalog (string) – Summary/Detailed/Proper Motions/Source Positions search
  • mag (string) – search MagAper2 or MagAuto for Summary
  • ra (string) – The RA to cone search against
  • dec (string) – The DEC to cone search against
  • radius (float) – The Radius for the cone search in degrees
  • sr (float) – The Radius for the cone search in degrees (alternative to radius)
  • nd (int) – Query level (Detailed spatial search only, default 0) 0) All detected sources 1) Detections and filter-based non-detections 2) Detections, filter-based non-detections, and visit-based non-detections
  • columns (string) – A list of column names to include
  • sort_by (string) – A list of columns to sort by
  • remove_null_columns (boolean) – Flag to remove columns with all null values (default True)
GET /hsc/(summary)/(magaper2|magauto)/count.*/?

Search for filtered HSC results and return count if specified (/count)

Parameters:
  • catalog (string) – Summary/Detailed/Proper Motions/Source Positions search
  • mag (string) – search MagAper2 or MagAuto for Summary
  • ra (string) – The RA to cone search against
  • dec (string) – The DEC to cone search against
  • radius (float) – The Radius for the cone search in degrees
  • sr (float) – The Radius for the cone search in degrees (alternative to radius)
  • nd (int) – Query level (Detailed spatial search only, default 0) 0) All detected sources 1) Detections and filter-based non-detections 2) Detections, filter-based non-detections, and visit-based non-detections
  • columns (string) – A list of column names to include
  • sort_by (string) – A list of columns to sort by
  • remove_null_columns (boolean) – Flag to remove columns with all null values (default True)
GET /hsc/(detailed|propermotions|sourcepositions).*/?

Search for filtered HSC results and return count if specified (/count)

Parameters:
  • catalog (string) – Summary/Detailed/Proper Motions/Source Positions search
  • mag (string) – search MagAper2 or MagAuto for Summary
  • ra (string) – The RA to cone search against
  • dec (string) – The DEC to cone search against
  • radius (float) – The Radius for the cone search in degrees
  • sr (float) – The Radius for the cone search in degrees (alternative to radius)
  • nd (int) – Query level (Detailed spatial search only, default 0) 0) All detected sources 1) Detections and filter-based non-detections 2) Detections, filter-based non-detections, and visit-based non-detections
  • columns (string) – A list of column names to include
  • sort_by (string) – A list of columns to sort by
  • remove_null_columns (boolean) – Flag to remove columns with all null values (default True)
GET /hsc/(detailed|propermotions|sourcepositions)/count.*/?

Search for filtered HSC results and return count if specified (/count)

Parameters:
  • catalog (string) – Summary/Detailed/Proper Motions/Source Positions search
  • mag (string) – search MagAper2 or MagAuto for Summary
  • ra (string) – The RA to cone search against
  • dec (string) – The DEC to cone search against
  • radius (float) – The Radius for the cone search in degrees
  • sr (float) – The Radius for the cone search in degrees (alternative to radius)
  • nd (int) – Query level (Detailed spatial search only, default 0) 0) All detected sources 1) Detections and filter-based non-detections 2) Detections, filter-based non-detections, and visit-based non-detections
  • columns (string) – A list of column names to include
  • sort_by (string) – A list of columns to sort by
  • remove_null_columns (boolean) – Flag to remove columns with all null values (default True)
POST /hsc/crossmatch/upload.*/?

Search HSC 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 in degrees
  • resolve (boolean) – resolve passed targets/coordinates
  • remove_null_columns (boolean) – Flag to remove columns with all null values (default True)
Return:

DB result of crossmatch

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

POST /hsc/crossmatch.*/?

Search HSC 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 in degrees
  • resolve (boolean) – resolve passed targets/coordinates
Return:

DB result of crossmatch