Cosmo Webpage

API Reference

Endpoint Listing and Descriptions

Endpoint	Description	Argument
/pig/	Get the list of PIG folders available for querying along with the halo numbers and redshifts
/pig/{id}	Get snapshot info in PIG_{id}	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271].
/pig/{id}/{ptype}	Get the list of {ptype} particle features available for querying in PIG_{id}	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271]. { ptype }: Name of particle type. It should be a string and in ['gas', 'dm', 'star', 'bh'].
/pig/{id}/fofgroup	Get the list of FoFgroup features available for querying in PIG_{id}	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271].
/pig/{id}/lengthbytype/n={num}	Get the length info of the first {num} halos in PIG_{id}	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271]. { num }: Number of halos. It should be an integer and be between 1 to the max halo size.
/pig/{id}/lengthbytype/{halo_id}/{type_id}	Get the number of {type_id} particles in the {halo_id}th halo in PIG_{id}	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271]. { halo_id }: ID of a halo. It should be an integer and be between 0 to the max halo ID. { type_id }: ID of particle type. It should be an integer and between [0,6).
/pig/{id}/{ptype}/{feature}/{group_id}	Get the {feature} data of {ptype} particle in {group_id} group and PIG_{id} folder	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271]. { feature }: Feature of a particle type. It should be a string. Eg. "Density", "ElectronAbundance", "H2Fraction", etc. { group_id }: ID of a halo group. It should be an integer and be between 1 to the max halo group size.
/pig/{id}/lengthbytype/?{group_query}	Execute {group_query} and get the length info of the a list of halos in PIG_{id}	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271]. { group_query }: A list of group IDs. It should be a list and pass as a query parameter.
POST/pig/{id}/{ptype}/{feature}/, data = {ID_list}	Get all {feature} data of {ptype} particle in the group {ID_list} and PIG_{id} folder	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271]. { ptype }: Name of particle type. It should be a string and in ['gas', 'dm', 'star', 'bh']. { feature }: Feature of a particle type. It should be a string. Eg. "Density", "ElectronAbundance", "H2Fraction", etc. { ID_list }: A list of group IDs. It should be a list and pass as request body with post method.
/pig/{id}/search/{ptype}/{feature}/{criterion}/?{range_query}	Get a dictionary of {groupid:data} for data of {feature} {ptype} particle within the searching {criterion}.	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271]. { ptype }: Name of particle type. It should be a string and in ['gas', 'dm', 'star', 'bh']. { feature }: Feature of a particle type. It should be a string. Eg. "Density", "ElectronAbundance", "H2Fraction", etc. { criterion }: Searching criterion. It should be a string and in ['bh_mass', 'gas_mass', 'dm_mass', 'star_mass', 'bh_mdot']. { range_query }: The min_range and max_range of a certain criterion. Both min_range and max_range are float, and pass as an optional query parameter.
/pig/{id}/fofgroup/{fof_feature}/{group_id}	Get the {feature} data of FOFGroup in {group_id} group and PIG_{id} folder	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271]. { group_id }: ID of a halo group. It should be an integer and be between 1 to the max halo group size. { fof_feature }: Feature of a FOFGroup. It should be a string. Eg. "LengthByType", "OffsetByType", "MassByType", etc.
/pig/{id}/search_id/{ptype}/{fof_feature}?{range_query}	Get all halo IDs of {ptype} particles for {feature} matching some searching {range_query} criterion in a PIG_{id} folder	{ id }: ID of a pig folder. It should be an integer and in [184, 197, 208, 216, 222, 230, 237, 244, 251, 258, 265, 271]. { ptype }: Name of particle type. It should be a string and in ['gas', 'dm', 'star', 'bh']. { range_query }: The min_range and max_range of a certain criterion. Both min_range and max_range are float, and pass as an optional query parameter. { fof_feature }: Feature of a FOFGroup. It should be a string. Eg. "LengthByType", "OffsetByType", "MassByType", etc.

Data Access:

The web-based API interface can respond to a variety of user requests and queries. To access the it, please click "http://bluetides-api.psc.edu/docs".

Search Requests:

Several API functions accept additional, optional query parameters, descriptions are as belows:

{group_query} is a list of group IDs. For example:

For bulk queries of halo data, the data of several halos can be extracted by inputing an ID list as query parameters. Example usage:
- To get length data of halo 4, 5, 6:
  Request: request.get("/pig/251/lengthbytype/", params = {'haloid_list': [4,5,6]})
  URL: "/pig/251/lengthbytype/?haloid_list=4&haloid_list=5&haloid_list=6"
  Return: {ID1:data_id1, ID2:data_id2...}

{range_query} is the min_range and max_range of a certain criterion. For example:

For searching criterion by field query, an halo ID list can be returned when the particular pariticle feature matches some searching criterion, and the min_range and max_range are passed as optional query parameters. Example usage:
- Get all halo ids if the halo BH total mass is between some threshold:
  Request: request.get("/pig/271/search/bh/BlackholeMass/bh_mass",params={"min_range":5e-3,"max_range":1e-2})
  URL: "/pig/271/search/bh/BlackholeMass/bh_mass?min_range=5e-3&max_range=1e-2"
  Return: ID_list

Some API functions accept post method to pass necessary data in request body, descriptions are as belows:

{ID_list} is a list of group IDs. For example:

Again, for bulk queries of halo data, data of several halos can be extracted by pass an ID list as request body. Example usage:
- To get gas position data of group 1, 2, 3:
  Request: request.post("/pig/251/dm/Potential/", data = '[1,2,3]')
  URL: "/pig/251/gas/Position/"
  
  Return: {ID1:data_id1, ID2:data_id2...}
In comparison with the previous get method, this way enables passing a larger ID list, since it wouldn't cause the URL to be too long.

Response Codes:

The Cosmo API will return a subset of standard HTTP response codes, in particular:

200 - Success. Response is being returned as requested.
400 - Bad Request. The server will not process the request, because it appears to contain an error.
404 - Not Found. Either there is no API endpoint at the URL which you requested, or you have requested a data resource which does not exist. For example, requesting length by type with a halo id for which it is not currently available.
500 - Server Error. Our fault! Please let us know if this happens.

Rest API Glossary:

Code method: a specific function in the code for performing a desired behavior. For example, a function for reading the list of files in a directory.
Resource: the actual data that is of interest for users.
Arguments: the parameters needed for filtering the set of results returned from a resource.
URL: a specific web address pointing to a resource.
Request: a petition sent to a web service, e.g. navigating to an URL.
API: "a set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service." In short, a set of code methods that use standard web interfaces and technologies for providing clients with results for valid queries. More info can be found on the OpenAPI documentation.
HTTP Request methods: "the desired action to be performed for a given resource” for use with the HTTP protocol. Meaning, a DELETE request pointed to a resource should perform an action that removes that resource, or the data associated with it. More info can be found in the Mozilla documentation.
Endpoint: It's a specific URL for accessing a resource from the API. The endpoints indicate how you access the resource, while the HTTP method indicates the allowed interactions (such as GET, POST, or DELETE) with the resource.
Query: a specific search or consultation to send to an endpoint.
Query string: the complete string for a query needed for sending a request to an endpoint, including the values for all of the arguments.

Full-path examples

The followings are absolute URLs for the cosmo API.