GET

/tiling

show/hide

Description

Calculates observation positions, "tiles", for a given multi-messenger event.

Query Parameters:

Parameter	Default	Type	Usage	Required	Description
uid	None	String	?uid=your-astro-colibri-uid	True	Your Astro-COLIBRI user id. Authenticates the request and identifies the account against which the per-user daily rate limit is counted. Requests without a valid uid are rejected (401 / 403).
url_map	None	String	?url_map="Encoded URL"	True	Encoded URL to access the localisation map. Only URL from ligo.org are currently accepted. Reference for encoding : https://en.wikipedia.org/wiki/URL_encoding
start_obs_time	None	String (ISO Format)	?start_obs_time=2023-01-01T00:00:00+01:00	True	Earliest time to start observations
latitude_obs	None	Float	?latitude_obs=-20.00	True	Latitude of the observatory in degree
longitude_obs	None	Float	?longitude_obs=10.00	True	Longitude of the observatory in degree
altitude_obs	None	Float	?altitude_obs=1855.0	True	Altitude of the observatory in meter
fov	2.0	Float	?fov=2.0	False	The size of the FoV of the instrument in degree
max_zenith	70.0	Float	?max_zenith=70.0	False	Maximum zenith angle allowed for observations in degree
sun_horizon	-18.0	Float	?sun_horizon=-18.0	False	Sun elevation (in degree) under which it is possible to perform observations. Common values: -18° for astronomical twilight (optical), -12° for nautical twilight, 90° for daytime observations (e.g., radio, HAWC, LHAASO).
moon_horizon	-0.5	Float	?moon_horizon=-0.5	False	Moon elevation (in degree) under which the night will be considered dark. Set to 90 for daytime observations (e.g., radio telescopes).
maximum_moon_phase	1.0	Float	?maximum_moon_phase=0.6	False	Maximum illumination fraction of the moon allowed for observations (0.0 = new moon, 1.0 = full moon). Only applies when moon is above moon_horizon. IACTs typically use 0.4-0.85.
minimum_moon_separation	0	Float	?minimum_moon_separation=30.0	False	Minimum separation between the pointing and the moon in degree (only apply if moon is above moon_horizon)
maximum_moon_separation	180	Float	?maximum_moon_separation=140.0	False	Maximum separation between the pointing and the moon in degree (only apply if moon is above moon_horizon)
max_nb_pointing	20	Int	?max_nb_pointing=200	False	Maximum number of tiles in the schedule
max_nb_obs_night	1	Int	?max_nb_obs_night=1	False	Number of nights for which it is allowed to schedule observations
pointing_obs_time	30	Float	?pointing_obs_time=30.0	False	Observation time for each tile (in minute)
min_pointing_obs_time	10	Float	?min_pointing_obs_time=10.0	False	Minimum observation time required for a tile (in minute)
max_distance_3D	250	Float	?max_distance_3D=250.0	False	The 3D galaxy-targeting algorithm is used if the event distance + 2σ is below this value (in Mpc). For nearby GW events, this enables galaxy-catalog-based scheduling. Should not exceed 500 Mpc.
containment_fraction_explored	0.9	Float	?containment_fraction_explored=0.9	False	Tiles will be searched only within the sky region corresponding to this containment fraction of the probability map (e.g., 0.9 = 90% credible region).
min_probability_tile	2e-9	Float	?min_probability_tile=0.01	False	A tile will be valid only if the covered probability exceeds this value. Higher values (e.g., 0.01) focus on high-probability regions only.
name_tilling	None	String	?name_tilling=my_fabulous_tilling	False	Name to give to the tiling operation
name_event	None	String	?name_event=my_fabulous_event	False	Name of the event to be analyse (only impacting the name given by the API, not the tiling solution)

Response fields:

_id

show/hide

Field	Type	Description
_id	String	unique ID for the schedule

tilepy_settings

show/hide

Field	Type	Description
url_map	String	Encoded URL to access the localisation map. Only URL from gracedb.ligo.org, heasarc.gsfc.nasa.gov or roc.icecube.wisc.edu are currently accepted. Reference for encoding : https://en.wikipedia.org/wiki/URL_encoding
start_obs_time	String (ISO Format)	Earliest time to start observations
latitude_obs	Float	Latitude of the observatory in degree
longitude_obs	Float	Longitude of the observatory in degree
altitude_obs	Float	Altitude of the observatory in meter
fov	Float	The size of the FoV of the instrument in degree
max_zenith	Float	Maximum zenith angle allowed for observations in degree
sun_horizon	Float	Sun elevation (in degree) under which it is possible to perform observation. Example:-18 for astronomical night, 90 for daylight observations
moon_horizon	Float	Moon elevation (in degree) under which, night will be considered dark
maximum_moon_phase	Float	Maximum illumination fraction of the moon possible for observations, the value should be between 0 and 1 (only apply if moon is above moon_horizon)
minimum_moon_separation	Float	Minimum separation between the pointing and the moon in degree (only apply if moon is above moon_horizon)
maximum_moon_separation	Float	Maximum separation between the pointing and the moon in degree (only apply if moon is above moon_horizon)
max_nb_pointing	Int	Maximum number of tiles in the schedule
max_nb_obs_night	Int	Number of nights for which it is allowed to schedule observations
pointing_obs_time	Float	Observation time for each tile (in minute)
min_pointing_obs_time	Float	Minimum observation time required for a tile (in minute)
name_tilling	String	Name to give to the tiling operation

schedule

show/hide

Field	Type	Description
tilename	String	identifier for the current scheduling tile [tile_xxx]
ra	Float	Right ascension of the position to observe [deg]
dec	Float	Declination of the position to observe [deg]
ra_hms	String	Right ascension of the position to observe in HMS format
dec_dms	String	Declination of the position to observe in DMS format
obs_time_utc	String	Best time to start observations; format: YYYY-MM-DDThh:mm:ss
prob_fov	float	Estimated probabilities for the events to be within this field of view

Usage example:

https://tilepy.com/tiling?uid=your-astro-colibri-uid&url_map=https%3A%2F%2Fgracedb.ligo.org%2Fapi%2Fsuperevents%2FS230528ay%2Ffiles%2Folib.multiorder.fits%2C1&start_obs_time=2023-05-28&latitude_obs=-23.27&longitude_obs=16.5&altitude_obs=1835

Associated JSON response

{
"_id": "ca95ec1b1083752d019362e65f56c82a9b017d5d",
"tilepy_settings": {
"moonGrey": 65.0,
"targetType": "GW",
"useGreytime": true,
"minSlewing": 2.0,
"online": false,
"minimumProbCutForCatalogue": 1e-09,
"minProbcut": 2e-09,
"doPlot": false,
"secondRound": false,
"zenithWeighting": 0.75,
"reducedNside": 256,
"HRnside": 512,
"mangrove": false,
"event_name": "S230528ay",
"name_tilling": "1686835415629113",
"url_map": "https://gracedb.ligo.org/api/superevents/S230528ay/files/olib.multiorder.fits,1",
"start_obs_time": "2023-05-28T00:00:00",
"latitude_obs": -23.27,
"longitude_obs": 16.5,
"altitude_obs": 1835.0,
"sun_horizon": -18.0,
"moon_horizon": -0.5,
"maximum_moon_phase": 100.0,
"minimum_moon_separation": 0.0,
"maximum_moon_separation": 180.0,
"max_zenith": 70,
"fov": 2.0,
"max_nb_pointing": 20,
"max_nb_obs_night": 1,
"pointing_obs_time": 30.0,
"min_pointing_obs_time": 10.0,
"maximum_distance_3D": 500.0,
"containment_fraction_explored": 0.9
},
"schedule": {
"tile_000": {
"dec": -7.1808,
"dec_dms": "-07:10:50.88",
"obs_time_utc": "2023-09-20T19:36:43",
"prob_fov": 0.3382,
"ra": 1.9336,
"ra_hms": "00:07:44.064"
}, "tile_001": { "dec": -10.8069,
"dec_dms": "-10:48:24.84",
"obs_time_utc": "2023-09-20T20:06:43",
"prob_fov": 0.2165,
"ra": 2.9883,
"ra_hms": "00:11:57.192"
},
"tile_002": {
"dec": -3.5833,
"dec_dms": "-03:34:59.88",
"obs_time_utc": "2023-09-20T20:36:43",
"prob_fov": 0.2159,
"ra": 0.8789,
"ra_hms": "00:03:30.936"
},
"tile_003": {
"dec": -14.1695,
"dec_dms": "-14:10:10.2",
"obs_time_utc": "2023-09-20T21:06:43",
"prob_fov": 0.0753,
"ra": 4.3945,
"ra_hms": "00:17:34.68"
},
"tile_004": {
"dec": -0.5968,
"dec_dms": "-00:35:48.48",
"obs_time_utc": "2023-09-20T21:36:43",
"prob_fov": 0.0446,
"ra": 0.1758,
"ra_hms": "00:00:42.192"
},
....
}
}