A custom component for Home Assistant that retrieves NEO data from NASA.
NASA's Near-Earth Object (NEO) program focuses on detecting, tracking, and characterizing potentially hazardous asteroids and comets that could approach Earth, with the goal of understanding and mitigating potential risks.
They watch, so you don't have to worry.
For each Near Earth Object you choose to track, a link is created to NASA's NEO Orbital Viewer,
which is especially fascinating as it gives you an incredible 4D model that shows you how the object will pass through our solar system over time.
(That's NASA's work!)
An example of how to display the information on a page is given here:
Download this example Home Assistant page yaml here
This component takes the data for the next 1 week (up to 2 years) provided by the NASA Near Earth Object Web Service
For your chosen time period, it can show you anything from the top 1 to the top 20 "potentially dangerous" and non "potentially dangerous" objects passing by Earth.
There is also the option of watching specific NEOs (like everyone's favourite "2024 YR4").
The sensors contain attributes including speed, size, how close to earth it will get, and the date that it will be at it's closest, or the next time it will be close.
Click here to find out why I created this component
I created this Home Assistant integration for two reasons
-
Because NASA has made this information public
I had been searching for public API's with interesting information that I could display on HA.
I wanted to learn more about what it takes to create an integration and expose entities with attributes. -
Because the NEO project is a testament to human curiosity and ingenuity.
It's a reminder that science is not just a subject in school; it's a powerful tool for understanding and safeguarding our world.
The more we know, the less we have to fear, and the more we can appreciate the incredible universe we live in.
This component is meant for people who are curious to know how often large, potentially dangerous objects pass us by on a monthly basis.If you're looking for an early warning system,
the NASA website and the mainstream news organisations will have the information before it's shown here, sorry.You can find out more about the NASA project here: https://science.nasa.gov/planetary-defense-neoo/
and here: https://cneos.jpl.nasa.gov/ca/neo_ca_intro.html
and here: https://neo.gsfc.nasa.gov/You can find out more about the NASA API here: https://api.nasa.gov/
You will need a NASA API key, don't worry, it's free (They just need your email address).
The key can be obtained here, under "Generate API Key": https://api.nasa.gov/
*Please mention this github repository under "How will you use the APIs?"
Have HACS installed on your Home Assistant.
- Adding NEO Watcher to HACS can be done using this button:
- Click Install on the
NEO Watcherintegration. - Restart Home Assistant.
Note
If the button above doesn't work, add https://github.com/danq8/neo_watcher as a custom repository with a type of Integration in HACS.
Manual installation
- Copy
neo_watcherfolder from latest release tocustom_componentsfolder in your config directory. - Restart the Home Assistant.
- go to Settings --> Devices & services, and click on "+ ADD INTEGRATION"
- Search for NEO Watcher, click on the result, enter your API key and click SUBMIT.
Simply go to Settings --> "Devices and services" --> "Add integration"
choose the NEO Watcher integration
You will then see this page:
Paste in your NASA API key,
choose between watching a particular object or having the top (closest) objects,
then choose what hour of day you want the data refreshed.
Configure Top NEOs
Here you'll be able to choose how far to look into the future in weeks (Maximum 2 years).
As well as whether you just want just the first closest top objects (potentially dangerous and non-potentially dangerous) all the way up to the top 20 objects.
Watch a specific NEO
Here you'll simply need to type in the name or designation of the object.
(You can find these on NASA's NEO page: [https://cneos.jpl.nasa.gov/ca/](https://cneos.jpl.nasa.gov/ca/)
Once initialised you should see the new sensors. There will be one showing the integration stats, along with how ever many NEOs you've selected to watch.
Contributing To The Project
  There are several ways of contributing to this project, they include:
-
Suggesting new sensors or NEO information as a feature request
using this link: Request a feature
-
Adding new sensors
-
Updating or improving the documentation
-
Helping answer/fix any issues raised
For further details see contributing guidelines.
This project uses the MIT Licence, for more details see the licence document.
If you like this project, please give it a star on GitHub
My appreciation goes out to NASA,
and especially the SpaceRocks Team: David Greenfield, Arezu Sarvestani, Jason English and Peter Baunach.
https://github.com/SpaceRocks/
I have to mention the amazing work of the Home Assistant team https://www.home-assistant.io/
And the HACS team https://www.hacs.xyz/
Also, I have to say a big thanks to Google Gemini, without whose help I couldn't have done it.
Gemini was a game collaborator, but did go off on a few tangents,
telling me on a few occasions that they were certain, certain, certain, certain that this time they had understood the errors from the logs, the hints and documentation I'd provided and that th
5915
e new, new, new, new suggestion would be the right one.
I'd liken working with Gemini 2.5 with walking a puppy in a park for the first time. Full of enthusiasm and energy, but a little too focused on the strange new bug crawling around on the ground, rather than on me calling it back to safety.
Between us we got the job done, and for that I'm grateful.
https://gemini.google.com/app