Skip to main content

​
Overview

The NasaApiService interface defines the network calls to NASA’s APOD API using Retrofit. It provides three main endpoints for fetching astronomy images and their metadata.
Base URL: https://api.nasa.gov/planetary/apod

​
Interface Definition

package com.ccandeladev.nasaexplorer.data.api

import retrofit2.http.GET
import retrofit2.http.Query

interface NasaApiService {
    @GET("planetary/apod")
    suspend fun getImageOfTheDay(
        @Query("api_key") apiKey: String,
        @Query("date") date: String? = null
    ): NasaResponse

    @GET("planetary/apod")
    suspend fun getImagesInRange(
        @Query("api_key") apiKey: String,
        @Query("start_date") startDate: String,
        @Query("end_date") endDate: String? = null
    ): List<NasaResponse>

    @GET("planetary/apod")
    suspend fun getRandomImages(
        @Query("api_key") apiKey: String,
        @Query("count") count: Int,
    ): List<NasaResponse>
}

​
API Methods

​
Get Image of the Day

Retrieves the Astronomy Picture of the Day for a specific date or today’s date.
​
apiKey
String
required
NASA API key for authentication
​
date
String
Date in YYYY-MM-DD format. If not provided, returns today’s image
​
response
NasaResponse
Single NASA image response with metadata including title, URL, date, and explanation
Example Usage: 
val todayImage = nasaApiService.getImageOfTheDay(
    apiKey = "YOUR_API_KEY"
)

val specificDate = nasaApiService.getImageOfTheDay(
    apiKey = "YOUR_API_KEY",
    date = "2024-01-15"
)

​
Get Images in Range

Fetches multiple astronomy images within a date range.
​
apiKey
String
required
NASA API key for authentication
​
startDate
String
required
Start date in YYYY-MM-DD format
​
endDate
String
End date in YYYY-MM-DD format. If not provided, uses current date
​
response
List<NasaResponse>
List of NASA image responses for each day in the specified range
Example Usage: 
val rangeImages = nasaApiService.getImagesInRange(
    apiKey = "YOUR_API_KEY",
    startDate = "2024-01-01",
    endDate = "2024-01-07"
)
Date ranges are limited to avoid excessive API calls. Consider pagination for large ranges.

​
Get Random Images

Retrrieves a specified number of random astronomy images.
​
apiKey
String
required
NASA API key for authentication
​
count
Int
required
Number of random images to retrieve (typically 1-100)
​
response
List<NasaResponse>
List of random NASA image responses
Example Usage: 
val randomImages = nasaApiService.getRandomImages(
    apiKey = "YOUR_API_KEY",
    count = 10
)

​
Configuration

This service interface is configured with Retrofit in the dependency injection module: 
@Provides
@Singleton
fun provideNasaApiService(retrofit: Retrofit): NasaApiService {
    return retrofit.create(NasaApiService::class.java)
}

​
Response Handling

All methods are suspend functions designed for Kotlin Coroutines. They should be called from a coroutine scope or another suspend function.
The API responses are mapped to domain models using the toNasaModel() extension function in the repository layer.

Build docs developers (and LLMs) love

Get started for freeTalk to us