What it is

OrbitFetcher is a C++ library that allows easy API calls to N2YO.com. Users can easily retrieve different satellite data sets with a simple function call. The returned data is parsed into ResponseData structs for easy access to data parameters. This library also comes with optional Python bindings.

API calls available:

• TLE
• Satellite positions
• Visual passes
• Radio passes
• Satellites above

Disclaimer

This is an independent project and is not affiliated with, endorsed by, or connected to N2YO.com. This library simply provides a C++ interface to their public API.

Building

Dependencies

• Curl
• Boost test
• Boost Python [Optional for Python bindings]
• nlohmann json
• CMake version 3.20 >=
• C++ 20 compatible compiler

Linux

After cloning the repository, using the terminal, cd into the project dir and run one of the following build configuration commands.

Debug with Python bindings:

cmake -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_PY_BINDINGS=ON

Debug no Python bindings:

cmake -B build -DCMAKE_BUILD_TYPE=Debug

Release with Python bindings:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_PY_BINDINGS=ON

Release no Python bindings:

cmake -B build -DCMAKE_BUILD_TYPE=Release 

Once configuration is complete run:

cd build && make

After successfully compiling the following will be built:

• OrbitFetcherTests
• OrbitFetcher.so

Windows

Installing Dependencies with vcpkg

This project uses vcpkg for dependency management on Windows. Follow the official vcpkg installation guide to set up vcpkg on your system.

Once vcpkg is installed, install the required packages:

vcpkg install curl

vcpkg install boost-python

vcpkg install boost-test

vcpkg install nlohmann-json

Note: The latest version of Python 3 available through vcpkg is currently 3.12. This is the maximum Python version supported for building Python bindings on Windows.

Building the Project

After installing dependencies, navigate to the project directory in PowerShell or Command Prompt and run one of the following build configuration commands:

Debug with Python bindings:

cmake -B build -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]\scripts\buildsystems\vcpkg.cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_PY_BINDINGS=ON

Debug without Python bindings:

cmake -B build -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]\scripts\buildsystems\vcpkg.cmake -DCMAKE_BUILD_TYPE=Debug

Release with Python bindings:

cmake -B build -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]\scripts\buildsystems\vcpkg.cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_PY_BINDINGS=ON

Release without Python bindings:

cmake -B build -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]\scripts\buildsystems\vcpkg.cmake -DCMAKE_BUILD_TYPE=Release

Once configuration is complete, build the project:

cmake --build build --config Debug

or for Release builds:

cmake --build build --config Release

After successfully compiling, the following will be built:

• OrbitFetcherTests.exe
• OrbitFetcher.pyd (if Python bindings are enabled)
• Required .dll files

Running tests

1. After successfully compiling, you need to make an account at N2YO.com to generate your API key.
2. In the build directory, open the orbitFetcherConfig.txt file and replace **YOUR API KEY HERE** with your API key and save the file.
3. Run: OrbitFetcherTests
4. Run: OrbitFetcherIntegrationTests

How to use

Using the library is very simple. There are two ways to instantiate the parameters needed for the API calls:

1. Use the orbitFetcherConfig.txtfile.
2. Directly pass API call parameters into the function calls.

Using the orbitFetcherConfig.txt

#include "OrbitFetcher/Config.h"
#include "OrbitFetcher/DataReceiver.h"

int main()
{
    // Create a Config object 
    OrbitFetcher::Config config;

    // Pass in the path to your orbitFetcherConfig.txt file to be read
    config.read("orbitFetcherConfig.txt);

    // Create an instance of the DataReceiver and pass the config object into the constructor 
    OrbitFetcher::DataReceiver receiver(config);

    // Get TLE using orbitFetcherConfig.txt configuration
    OrbitFetcher::ResponseData::Tle tle = receiver.getTle();

    // Get satellite position data using orbitFetcherConfig.txt configuration
    OrbitFetcher::ResponseData::SatellitePosition satellitePosition = receiver.getSatellitePosition();

    // Get satellite visual pass data using orbitFetcherConfig.txt configuration
    OrbitFetcher::ResponseData::SatelliteVisualPass visualPass = receiver.getSatelliteVisualPass();

    // Get satellite radio pass data using orbitFetcherConfig.txt configuration
    OrbitFetcher::ResponseData::SatelliteRadioPass radioPass = receiver.getSatelliteRadioPass();

    // Get satellites above using orbitFetcherConfig.txt configuration
    OrbitFetcher::ResponseData::SatellitesAbove satellitesAbove = receiver.getSatellitesAbove();
    
}

Parameter function calls

#include "OrbitFetcher/Config.h"
#include "OrbitFetcher/DataReceiver.h"

int main()
{
    const std::string apiKey {"abcd-1234-efgh-5678"};
    const int noradId {25544};
    const double observerLat {50.96081305800268};
    const double observerLon {-0.11800587771065109};
    const double observerAlt {0.0};
    const int searchRadius {90};
    const OrbitFetcher::SearchCategory searchCategory {OrbitFetcher::SearchCategory::All};
    const int seconds {10};
    const int days {10};
    const int minimumVisibility {3};
    const int minimumElevation {3};

    // Create an instance of the DataReceiver
    OrbitFetcher::DataReceiver receiver;

    // Get TLE using function parameters
    OrbitFetcher::ResponseData::Tle tle = receiver.getTle(apiKey, noradId);

    // Get satellite position data using function parameters
    OrbitFetcher::ResponseData::SatellitePosition satellitePosition = receiver.getSatellitePosition(apiKey, noradId, observerLat, observerLon, observerAlt, seconds);

    // Get satellite visual pass data using function parameters
    OrbitFetcher::ResponseData::SatelliteVisualPass visualPass = receiver.getSatelliteVisualPass(apiKey, noradId, observerLat, observerLon, observerAlt, days, minimumVisibility);

    // Get satellite radio pass data using function parameters
    OrbitFetcher::ResponseData::SatelliteRadioPass radioPass = receiver.getSatelliteRadioPass(apiKey, noradId, observerLat, observerLon, observerAlt, days, minimumElevation);

    // Get satellites above using function parameters
    OrbitFetcher::ResponseData::SatellitesAbove satellitesAbove = receiver.getSatellitesAbove(apiKey, observerLat, observerLon, observerAlt, searchRadius, searchCategory);

}

Getting config values

The config class has a helpful function that allows you to get individual values from the file that has been read in.

For example getting the API key from the file:

#include "OrbitFetcher/Config.h"

int main()
{
    OrbitFetcher::Config config;

    config.read("orbitFetcherConfig.txt");

    // Get API key from config file
    auto apiKey = config.getConfigValues().apiKey;
}

Response Data

Each function call returns a OrbitFetcher::ResponseData struct that holds all the data from the respective API call.

Python

Using the library with python is super simple. Build the library with --DBUILD_PY_BINDINGS=ON.

Linux

Copy the OrbitFetcher.so file and the orbitFetcherConfig.txt file into the root dir of your python project.

├── orbitFetcherConfig.txt
├── main.py
└── OrbitFetcher.so

Windows

Copy the OrbitFetcher.pyd, orbitFetcherConfig.txt and all the .dll files from your build directory into the root dir of your python project.

├── orbitFetcherConfig.txt
├── main.py
├── OrbitFetcher.pyd
├── boost_python312-vc145-mt-x64-1_90.dll
├── libcurl.dll
├── python312.dll
└── zlib1.dll

Example using orbitFetcherConfig.txt

import OrbitFetcher

config = OrbitFetcher.Config()

config.read("orbitFetcherConfig.txt")

dataReceiver = OrbitFetcher.DataReceiver(config)

tle = dataReceiver.getTle()
positions = dataReceiver.getSatellitePosition()
visualPass = dataReceiver.getSatelliteVisualPass()
radioPass = dataReceiver.getSatelliteRadioPass()
satsAbove = dataReceiver.getSatellitesAbove()

Example using function params:

import OrbitFetcher

dataReceiver = OrbitFetcher.DataReceiver()

tle = dataReceiver.getTle("abcd-1234-efgh-5678", 25544)

print(tle.tleStr)
    
# Other function calls work the same as cpp...

I have built a very basic satellite tracking application using matplotlib as an example satellite tracker. Feel free to check it out and have a play.

Note

Detailed explanations of each API call and its respective response can be found at https://www.n2yo.com/api/ along with usage limits for each call.