src.api.services.tools_service module

src.api.services.tools_service.get_active_satellites(sat_repo: AbstractSatelliteRepository, object_type: str | None, api_source: str, api_version: str)[source]

Fetches active satellites based on the provided object type (optional).

Parameters:

  • sat_repo (AbstractSatelliteRepository) – The repository to fetch satellite data

  • from. –

  • object_type (str) – The type of the object, either “payload”, “debris”,

  • body" ("rocket) –

  • "tba" –

  • "unknown". (or) –

  • api_source (str) – The source of the API request.

  • api_version (str) – The version of the API request.

Returns:

A dictionary containing:

  • count: number of satellites found

  • data: list of satellite data

  • source: API source

  • version: API version

Return type:

dict

src.api.services.tools_service.get_adjacent_tle_results(tle_repo: AbstractTLERepository, id: str, id_type: str, epoch: datetime, api_source: str, api_version: str, format: str = 'json') → list[dict[str, list[dict[str, Any]] | str]] | BytesIO[source]

Fetches the adjacent TLEs to a specific epoch date - one TLE before and one after.

Parameters:

  • tle_repo (AbstractTLERepository) – The repository to fetch TLE data from.

  • id (str) – The ID of the satellite.

  • id_type (str) – The type of the ID, either “catalog” or “name”.

  • epoch (datetime) – The epoch date to fetch the adjacent TLEs to.

  • api_source (str) – The source of the API request.

  • api_version (str) – The version of the API request.

  • format (str) – The format of the response, either “json” or “txt”.

Returns:

  • For JSON format: A list containing a dictionary with TLE data

  • For TXT format: A BytesIO object containing the formatted TLE text

Return type:

list[dict[str, list[dict[str, Any]] | str]] | io.BytesIO

src.api.services.tools_service.get_all_tles_at_epoch_formatted(tle_repo: AbstractTLERepository, epoch_date: datetime, format: str = 'json', page: int = 1, per_page: int = 100, api_source: str = '', api_version: str = '') → list[dict[str, Any]] | BytesIO[source]

Fetches all TLEs at a specific epoch date with support for different output formats.

Parameters:

  • tle_repo (AbstractTLERepository) – The repository to fetch TLE data from.

  • epoch_date (datetime) – The epoch date for the TLE data.

  • format (str) – Output format - either “json”, “txt”, or “zip”.

  • page (int) – The page number for pagination (used for JSON format).

  • per_page (int) – The number of results per page (used for JSON format).

  • api_source (str) – The source of the API request.

  • api_version (str) – The version of the API request.

Returns:

Either a list containing TLE data and pagination info (JSON) or a BytesIO object containing formatted TLE data (TXT/ZIP).

Return type:

list[dict[str, Any]] | io.BytesIO

src.api.services.tools_service.get_ids_for_satellite_name(sat_repo: AbstractSatelliteRepository, satellite_name: str, api_source: str, api_version: str)[source]

Fetches NORAD IDs associated with a given satellite name.

Parameters:

  • sat_repo (AbstractSatelliteRepository) – The repository instance used to fetch satellite data.

  • satellite_name (str) – The name of the satellite.

Returns:

A list of dictionaries containing the satellite name, NORAD ID, date added, and whether it is the current version. Each dictionary includes the following keys: - “name”: The name of the satellite. - “norad_id”: The NORAD ID of the satellite. - “date_added”: The date the NORAD ID was added. - “is_current_version”: A boolean indicating if it is the current

version.

Return type:

List[dict]

src.api.services.tools_service.get_names_for_satellite_id(sat_repo: AbstractSatelliteRepository, satellite_id: str, api_source: str, api_version: str)[source]

Fetches names associated with a given NORAD ID.

Parameters:

  • sat_repo (AbstractSatelliteRepository) – The repository instance used to fetch satellite data.

  • satellite_id (str) – The NORAD of the satellite.

Returns:

A list of dictionaries containing the satellite name, NORAD ID, date added, and whether it is the current version. Each dictionary includes the following keys:

  • ”name”: The name of the satellite.

  • ”norad_id”: The NORAD ID of the satellite.

  • ”date_added”: The date the NORAD ID was added.

  • ”is_current_version”: A boolean indicating if it is the current

    version.

Return type:

List[dict]

src.api.services.tools_service.get_nearest_tle_result(tle_repo: AbstractTLERepository, id: str, id_type: str, epoch: datetime, api_source: str, api_version: str) → list[dict[str, list[dict[str, Any]] | str]][source]

Fetches the nearest TLE to a specific epoch date.

This function retrieves the TLE from the repository that is closest to the specified epoch date.

Parameters:

  • tle_repo (AbstractTLERepository) – The repository to fetch TLE data from.

  • id (str) – The ID of the satellite.

  • id_type (str) – The type of the ID, either “catalog” or “name”.

  • epoch (datetime) – The epoch date to fetch the nearest TLE to.

  • api_source (str) – The source of the API request.

  • api_version (str) – The version of the API request.

Returns:

A single-item list containing a dictionary with: - tle_data: List of dictionaries, each containing:

  • satellite_name (str): Name of the satellite

  • satellite_id (int): NORAD catalog number

  • tle_line1 (str): First line of the TLE

  • tle_line2 (str): Second line of the TLE

  • epoch (str): Epoch of the TLE in ‘YYYY-MM-DD HH:MM:SS TZ’ format

  • date_collected (str): Date TLE was collected

  • data_source (str): Source of the TLE data

  • source (str): API source identifier

  • version (str): API version identifier

Return type:

list[dict[str, list[dict[str, Any]] | str]]

src.api.services.tools_service.get_satellite_data(sat_repo: AbstractSatelliteRepository, id: str, id_type: str, api_source: str, api_version: str)[source]

Fetches satellite data based on the provided ID and ID type.

This function retrieves satellite metadata from the repository based on the provided ID. The ID can be either a catalog ID or a satellite name, determined by the id_type parameter.

Parameters:

  • sat_repo (AbstractSatelliteRepository) – The repository to fetch satellite data

  • from. –

  • id (str) – The ID of the satellite, either a catalog ID or a satellite name.

  • id_type (str) – The type of the ID, either “catalog” or “name”.

  • api_source (str) – The source of the API request.

  • api_version (str) – The version of the API request.

Returns:

A list containing a dictionary with satellite data.

Returns an empty list if no satellite data is found.

Return type:

List[Dict[str, Any]]

Fetches and formats information about Starlink satellite generations.

This function retrieves data about different Starlink satellite generations, including their earliest and latest launch dates. The data is formatted into a standardized response structure.

Parameters:

  • sat_repo (AbstractSatelliteRepository) – The repository instance used to fetch Starlink generation data.

  • api_source (str) – The source identifier for the API request.

  • api_version (str) – The version identifier for the API request.

Returns:

A dictionary containing:

  • count (int): Number of Starlink generations found

  • data (list): List of dictionaries, each containing:

    • generation (str): The generation identifier

    • earliest_launch_date (str): The earliest launch date for this

    generation - latest_launch_date (str): The latest launch date for this generation

  • source (str): The API source identifier

  • version (str): The API version identifier

Return type:

dict

Raises:

Exception – If there is an error retrieving or formatting the generation data

src.api.services.tools_service.get_tle_data(tle_repo: AbstractTLERepository, id: str, id_type: str, start_date: datetime, end_date: datetime, api_source: str, api_version: str)[source]

Fetches Two-Line Element set (TLE) data for a given satellite.

This function retrieves TLE data from either the NORAD ID or satellite name provided. It allows for a date range to be specified for the TLE data, and if not provided, it will return all TLE data for the satellite.

Parameters:

  • tle_repo (AbstractTLERepository) – The repository instance used to fetch TLE data.

  • id (str) – The identifier for the satellite.

  • id_type (str) – The type of the ID, either ‘catalog’ (NORAD ID) or ‘name’.

  • start_date (datetime) – The start date of the date range for the TLE data.

  • end_date (datetime) – The end date of the date range for the TLE data.

Returns:

A list containing the TLE data for the specified satellite and date range. Each data point includes the satellite name, satellite ID, TLE lines, epoch, date collected, and data source.

Return type:

List[dict]

src.api.services.tools_service.get_tles_around_epoch_results(tle_repo: AbstractTLERepository, id: str, id_type: str, epoch: datetime, count_before: int, count_after: int, api_source: str, api_version: str)[source]

Fetches TLEs around a specific epoch date.

This function retrieves TLEs from the repository that are around the specified epoch date. It allows for a count of TLEs to be specified before and after the epoch date.

Parameters:

  • tle_repo (AbstractTLERepository) – The repository to fetch TLE data from.

  • id (str) – The ID of the satellite.

  • id_type (str) – The type of the ID, either “catalog” or “name”.

  • epoch (datetime) – The epoch date to fetch TLEs around.

  • count_before (int) – The number of TLEs to fetch before the epoch date.

  • count_after (int) – The number of TLEs to fetch after the epoch date.

Returns:

A list of dictionaries containing the TLE data.

Return type:

List[dict]

src.api.services.tools_service.search_all_satellites(sat_repo: AbstractSatelliteRepository, parameters: dict, api_source: str, api_version: str)[source]