APOD.Net 1.0.1

APOD.Net

APOD.Net is a .NET library used to asynchronously interface with NASA's Astronomy Picture of the Day API (APOD). The API features a different image or photograph of our universe each day, along with a brief explanation written by a professional astronomer. Here's what today's picture looks like!

⚡ Features

• 🚀 Fast, deadlock-free asynchronous library made in pure C# without external dependencies. ¹
• 🔓 Gives you access to all the undocumented features of NASA's API, such as getting all APODs between two dates and getting random APODs.
• 💻 Cross-platform support, targets .NET Standard 2.0 which is supported by .NET Core 2.0+, .NET Framework 4.6.1+ and many more. Click here for a full list of implementation support.
• 🔧 Takes care of everything you shouldn't have to care about. HTTP requests, mapping the JSON responses to .NET objects, validating input, etc.
• ✏️ Frictionless and easy to implement. One API request is one method call, as it should be.
• 📖 Continuously updated documentation! Click here to visit the docs.
• 💉 Completely dependency injection-friendly which allows you to easily override any functionality with your own implementations.

¹ - Uses System.Text.Json for deserializing the JSON. This is built-in as part of the .NET Core 3.0 framework but is installed as a NuGet package to be compatible with the targeted .NET Standard 2.0. Read more about System.Text.Json here.

🔍 Table of contents

• 📦 Adding APOD.Net to your project
  • Option 1 - Visual Studio PM Console
  • Option 2 - Visual Studio PM UI
  • Option 3 - dotnet.exe CLI
• 🌟 Getting started
  • Setting up the client
  • Making your first request
  • Interpreting the response
• 📁 More examples
• 💡 FAQ
• 📘 License

📦 Adding APOD.Net to your project

There are many different ways to add NuGet packages to your project. Below are some of the most common methods. Refer to this guide if you can't find a method that suits you.

Option 1 - Visual Studio PM Console

1. Open your project/solution in Visual Studio
2. Open the Package Manager Console by clicking Tools > NuGet Package Manager > Package Manager Console
3. In the Package Manager Console window, write the following command

   Install-Package APOD.Net
   

Option 2 - Visual Studio PM UI

1. Open your project/solution in Visual Studio
2. Open the NuGet Package Manager by clicking Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
3. Click Browse and search for APOD.Net and click APOD.Net by Marcus Otterström
4. Select the project you want to install the library in, select your desired version (Latest stable recommended) and click Install

Option 3 - dotnet.exe CLI

1. Open a shell/command prompt and navigate to the folder with your .csproj
2. Write the following command

   dotnet add package APOD.Net
   

🌟 Getting started

This guide is intended to be read in sequencial order as every topic builds on the preceding one. They share the same context. To get started, add the using directive.

using Apod;

Setting up the client

If you are new and just want to explore the API, you can create a new ApodClient using the parameterless constructor.

var client = new ApodClient();

This will use the API key DEMO_KEY which is provided by NASA as a way to explore their APIs. It has a rate limit of 50 requests daily per IP address.

For developing and using your application, you should sign up for an API key which has a rate limit of 1000 requests hourly per IP address. To initialize the ApodClient with your API key, use the ApodClient(String) constructor.

var client = new ApodClient("YOUR_API_KEY_HERE");

Making your first request

There are numerous available methods on the ApodClient, but for this simple example we are going to get the Astronomy Picture of the Day from my most recent birthday using ApodClient.FetchApodAsync(DateTime). I would get the APOD for your birthday, but I have no idea when that is. If I did, GitHub wouldn't be doing their GDPR right.

var date = new DateTime(2019, 06, 04);
var response = await client.FetchApodAsync(date);

Interpreting the response

The method we used in the example above, ApodClient.FetchApodAsync(DateTime), returns an ApodResponse. Instead of being impatient and immediately reading our APOD content we should make sure that the client didn't encounter any errors along the way. If the ApodResponse.StatusCode is not OK, we can get information about what went wrong in the ApodResponse.Error.

if (response.StatusCode != ApodStatusCode.OK)
{
    Console.WriteLine("Someone's done an oopsie.");
    Console.WriteLine(response.Error.ErrorCode);
    Console.WriteLine(response.Error.ErrorMessage);
    return;
}

Someone's done an oopsie.
ApiKeyInvalid
The API key you provided was invalid. Get one at https://api.nasa.gov/.

When we are certain that there were no errors we can read the content from the response. The ApodResponse.Content contains all the information about the Astronomy Picture of the Day. You can access properties such as Title, Explanation, Date, and ContentUrl (and more).

In the request we made previously we're expecting to get exactly one APOD, since we made a request for a specific date. To get our APOD, we read the value of the ApodResponse.Content field.

var apod = response.Content;
Console.WriteLine(apod.Title);
Console.WriteLine(apod.ContentUrl);
Console.WriteLine(apod.Explanation);

SEIS: Listening for Marsquakes
https://apod.nasa.gov/apod/image/1906/SeismometerClouds_Insight_1021.jpg
If you put your ear to Mars, what would you hear? To find out, and to explore the unknown interior of Mars, NASA's Insight Lander deployed SEIS late last year, a sensitive seismometer that can detect marsquakes. In early April, after hearing the wind and motions initiated by the lander itself, SEIS recorded an unprecedented event that matches what was expected for a marsquake.  This event can be heard on this YouTube video.  Although Mars is not thought to have tectonic plates like the Earth, numerous faults are visible on the Martian surface which likely occurred as the hot interior of Mars cooled -- and continues to cool.  Were strong enough marsquakes to occur, SEIS could hear their rumbles reflected from large structures internal to Mars, like a liquid core, if one exists.  Pictured last week, SEIS sits quietly on the Martian surface, taking in some Sun while light clouds are visible over the horizon.   Create a Distant Legacy: Send your name to Mars

If we're expecting more than one APOD from our request (for example if we asked for the APODs between two dates), we can get all of the APODs by reading the value of the ApodResponse.AllContent field.

foreach(var apod in response.AllContent)
{
    var formattedDate = apod.Date.ToString("MMMM d, yyyy");
    Console.WriteLine($"{formattedDate}: \"{apod.Title}\".");
}

Example request

var startDate = new DateTime(2008, 10, 29);
var endDate = new DateTime(2008, 11, 02);
var response = await client.FetchApodAsync(startDate, endDate);

Example response

October 29, 2008: "Mirach's Ghost".
October 30, 2008: "Haunting the Cepheus Flare".
October 31, 2008: "A Witch by Starlight".
November 1, 2008: "A Spectre in the Eastern Veil".
November 2, 2008: "Spicules: Jets on the Sun".

Disposing the client

Since the ApodClient uses an HttpRequester which in turn uses an HttpClient which should be disposed, the ApodClient is responsible for cleaning up the HttpClient.

To do this, call the Dispose() method on the client when you are done using it. The client will become unusable after calling this method.

client.Dispose();

If you are only going to use the ApodClient once in your application, you can construct and use it in a using statement. The client will not be usable outside the block and will be disposed of correctly.

using (var client = new ApodClient("YOUR_API_KEY_HERE"))
{
    // Use client here
}

💡 Bonus tip: If you are using C# 8.0 or later, you can use the alternative syntax for the using statement that doesn't require braces. The client will be disposed of when it falls out of scope.

using var client = new ApodClient("YOUR_API_KEY_HERE");

📁 More examples

You can find more examples in the documentation.

💡 FAQ

Can't find your question here? Feel free to open an issue!

• Disposable object created by 'new ApodClient()' is never disposed
• When do new APODs get published by NASA?
• What does ApodResponse.Content return if ApodResponse.AllContent has more than one APOD?
• What do I use the ApodClient(String, IHttpRequester, IHttpResponseParser, IErrorHandler) constructor for?

Disposable object created by 'new ApodClient()' is never disposed

Read the chapter "Disposing the client".

When do new APODs get published by NASA?

Because of daylight saving time, it depends. NASA is running the code in the Eastern Time Zone.

The table below will likely change in the future. Thanks, time zones.<br>

Want to learn more about the problems with time zones? Watch this youtube video from Computerphile (featuring Tom Scott).

When was the first APOD published?

The first APOD was published June 16th 1995 (link). However, the next 3 dates, June 17th, June 18th and June 19th, do not have any APODs.

In conclusion, there has been an Astronomy Picture of the Day every single day from June 20th 1995 and onward.

What does ApodResponse.Content return if ApodResponse.AllContent has more than one APOD?

ApodResponse.Content will return the APOD with the most recent date.

What do I use the ApodClient(String, IHttpRequester, IHttpResponseParser, IErrorHandler) constructor for?

You can use this constructor to override the behaviour of the ApodClient to your liking. Maybe you know some secret optimizing tricks (if you do, open a pull request) or maybe you want custom error handling. In that case you can inject your own implementation of IErrorHandler.

📘 License

APOD.Net is licensed under the MIT License. Read the full license here.