How to use Stellarium HTTP API
Okay folks. We have to be honest. If you never heard about Stellarium, you have to. You have to try this software just to see how incredible is it. But honestly, the docs about the HTTP API sucks.
Stellarium ?
Stellarium is a free open source planetarium for your computer. It shows a realistic sky in 3D, just like what you see with the naked eye, binoculars or a telescope.
This is what you can read on the official site of the software — and this is freaking amazing. There is everything; you can download it, or even get the complete code on Github.
I am not really into astrology or astronomy. I don’t even know the difference. Well, now I know because I just found it gross while I am writing to not know the difference. Stellarium is definitely about astronomy.
Here comes a project for school. With my team, we decided to imagine a kind of planetarium dome where you can see constellations about greek mythology. You just stand in this dome and with the help of your hands, you can move the sky just in front of you and explore the constellation.
For that, we need data. Data about constellations and stars. Here comes the challenge. Find an API with HTTP access. There is a lot. But a lot is too much hard to use. Stellarium seemed pretty complete and easy to use. Haha. Forget the word easy.
Stellarium doc HTTP API
When you are looking for information about it, you will probably find these links ;
- RemoteControl plugin HTTP API description
- RemoteControl plugin web interface
- RemoteControl Plug-in documentation
Well, I can tell you that I tried a lot of API. I never so much yelled against my computer. Just for fun, try these links and understand how to access to the API, please.
How to access the Stellarium API
The tutorial begins here. Be ready, because this is so fucking simple that I wanted to throw my so-love and sweet computer out of the window.
Prequesite
You have to download the software and install it. You can download it here. About installation, it seems pretty simple but you have all the documentation here ( A download will start by clicking on this link. This is the PDF User Manual ).
Here is the thing that is not mentioned. To have access to the API, you have to install the software AND the RemoteControl plugin. It will by itself create a localhost server when you launched it and only after it, you will be able to use the API.
Install the RemoteControl plugin
Well, after you have installed Stellarium, you can launch it. You normally arrive on something similar to this, depending on your location.
First step; install the RemoteControl plugin. To do so, you can click on the button with a spanner on the top right corner or press f2. A window should be opened.
Second step; you just have to select the Plugins tab and then find Remote Control in the list on the left. You can check “Load at startup” at the bottom of the window and then click on the “configure” button. You should have another window that looks like that.
Well, this is not finished. You have to check the two boxes on the top like on the screenshot. If you want to, you can use another port number and activate the authentification. I will not do it here.
When you have done it, you can save what you did and quit the software. Now if you reload Stellarium, the server will be running. You can try by going on the localhost with the port number you settled. http://localhost:8090 in my case. If you have this home page, then it means that it works! Congrats folks!
Access to the HTTP API
The useful is done. Haha. I swear to god that it takes me like 2 or 3 hours to find out. Thanks to Stack Overflow. Sorry, I don’t find the post anymore.
The response format could be in JSON and this is quite practical.
Now, you have access to the web interface, you have finally access to the API. You just have to add /api/ after the URL. Okay, if you only type /api/, you will receive this response.
Well, not really helpful…
The HTTP API of Stellarium
I will not rewrite all the documentation, but it will be cool that I show you how to use it. That’s okay, it’s my pleasure.
You can find on this page all the requests you can do. I will use one example. All the other requests are pretty built on the same pattern.
Imagine, you want to get information on your favorite constellation, Leo. The HTTP request will be http://localhost:8090/api/objects/info?name=leo&format=json. If I analyze the URL, you can see two keywords; objects and info. As you saw in the screenshots above, objects is the ObjectService service where you can find many GET or POST operations. Here we want the info operation which is a GET one—well, ObjectService only has GET operations. In the URL you have to precise the service first — here “objects”—then the operation—info in this case. Parameters are explained in the description of the operation. Here is the response I have.
Conclusion
I hope it will help some people to use this thing!
I find that the documentation sucks at this point. I mean, this is an incredible open-source project, but this is so difficult to understand that you don’t even want to use it.
Documentations are crucial. This is important to make them human-readable.
