A GET request to the Astronomy Picture of the Day (APOD) web service on September 18, 2020, returned the above photo of the spiral galaxy Arp 78. APOD is one of many APIs available through NASA Open APIs. Like APOD, some include imagery, such as the Earth Polychromatic Imaging Camera (EPIC) API, which returns images like this: Others include data. The Coronal Mass Ejection Analysis API, which is part of the DONKI suite of space weather forecasting tools, returns data that looks like this: [ { : , : , : , : , : , : , : , : , : , : , : }, { : , : , : , : , : , : , : , : , : , : , : } ] "time21_5" "2016-09-06T14:18Z" "latitude" -20.0 "longitude" 120.0 "halfAngle" 31.0 "speed" 674.0 "type" "C" "isMostAccurate" true "associatedCMEID" "2016-09-06T08:54:00-CME-001" "note" "" "catalog" "SWRC_CATALOG" "link" "https://kauai.ccmc.gsfc.nasa.gov/DONKI/view/CMEAnalysis/11233/-1" "time21_5" "2016-09-15T04:24Z" "latitude" -18.0 "longitude" -122.0 "halfAngle" 43.0 "speed" 722.0 "type" "C" "isMostAccurate" true "associatedCMEID" "2016-09-14T23:36:00-CME-001" "note" "Measured with swpc_cat using C3 and STA Cor2 imagery." "catalog" "SWRC_CATALOG" "link" "https://kauai.ccmc.gsfc.nasa.gov/DONKI/view/CMEAnalysis/11256/-1" In this article, we'll dig into an API that, like the one above, returns NASA data in JSON format. We’ll explore a small portion of all the available information provided through NASA Open APIs. We'll visualize that data with a Python library called Bokeh to help contextualize it for the viewer. Check out the interactive visualization created in this tutorial or see the code on GitHub. The NeoWs API The Near Earth Object Webservice (NeoWs) API caught my attention immediately, because... well, who wouldn't want to know about asteroids hurtling towards earth at this very moment? The NASA Open APIs documentation describes it this way: "NeoWs (Near Earth Object Web Service) is a RESTful web service for near earth Asteroid information. With NeoWs a user can: search for Asteroids based on their closest approach date to Earth, lookup a specific Asteroid with its NASA JPL small body id, as well as browse the overall data-set." NeoWs data is also relatively accessible for someone like myself with no subject matter knowledge. Unlike some of the space weather APIs, which I find mostly unintelligible with my lack of space weather training, NeoWs returns data with self-explanatory keys like "estimated_diameter" and "miss_distance": { :{ : , : , : }, : , :{ :[ { :{ : }, : , : , : , : , : , :{ :{ : , : }, :{ : , : }, :{ : , : }, :{ : , : } }, : , :[ { : , : , : , :{ : , : , : }, :{ : , : , : , : }, : } ], : }, ... "links" "next" "http://www.neowsapp.com/rest/v1/feed?start_date=2020-09-30&end_date=2020-09-30&detailed=false&api_key=DEMO_KEY" "prev" "http://www.neowsapp.com/rest/v1/feed?start_date=2020-09-28&end_date=2020-09-28&detailed=false&api_key=DEMO_KEY" "self" "http://www.neowsapp.com/rest/v1/feed?start_date=2020-09-29&end_date=2020-09-29&detailed=false&api_key=DEMO_KEY" "element_count" 12 "near_earth_objects" "2020-09-29" "links" "self" "http://www.neowsapp.com/rest/v1/neo/54054531?api_key=DEMO_KEY" "id" "54054531" "neo_reference_id" "54054531" "name" "(2020 SN2)" "nasa_jpl_url" "http://ssd.jpl.nasa.gov/sbdb.cgi?sstr=54054531" "absolute_magnitude_h" 24.431 "estimated_diameter" "kilometers" "estimated_diameter_min" 0.0345425963 "estimated_diameter_max" 0.0772395934 "meters" "estimated_diameter_min" 34.5425962673 "estimated_diameter_max" 77.239593373 "miles" "estimated_diameter_min" 0.0214637676 "estimated_diameter_max" 0.0479944434 "feet" "estimated_diameter_min" 113.3287315376 "estimated_diameter_max" 253.4107475218 "is_potentially_hazardous_asteroid" false "close_approach_data" "close_approach_date" "2020-09-29" "close_approach_date_full" "2020-Sep-29 13:21" "epoch_date_close_approach" 1601385660000 "relative_velocity" "kilometers_per_second" "8.7170431155" "kilometers_per_hour" "31381.355215948" "miles_per_hour" "19499.1537451539" "miss_distance" "astronomical" "0.1257314283" "lunar" "48.9095256087" "kilometers" "18809153.865737721" "miles" "11687466.2571577098" "orbiting_body" "Earth" "is_sentry_object" false It also contains the eminently important "is_potentially_hazardous_asteroid" key. I didn't include this information in the visualization in this article because I optimistically assume this key will almost always be set to false. NeoWs data is retrieved with a simple GET request: GET https: //api.nasa.gov/neo/rest/v1/feed?start_date=START_DATE&end_date=END_DATE&api_key=API_KEY Visualizing Asteroids Although it's clear what fields like "miss_distance" mean, the JSON data alone doesn't give us much sense of perspective. This is where our Bokeh visualization comes in. We will create a chart that looks like created on September 27th: this one This plot contains circles representing asteroids that reached their closest distance to Earth on the day the code was run (in this case, on September 27th). The time the asteroid approaches Earth is in UTC along the X-axis and miss distance in miles is along the Y-axis. The relative size of each asteroid is given by the radius of each circle. The size of all asteroids on our plot is scaled up by a factor of a million. This is so that they are visible despite the Y-axis being in millions of miles and the largest asteroid on the plot being less than a mile across. The moon is plotted in blue in the lower left-hand corner of the chart. This is to give the viewer a sense of how far the asteroids really are from Earth. The moon's radius is not to scale relative to the asteroids, as it is much larger than the largest asteroid on the chart and, if scaled up by a factor of a million, would be larger than the chart itself. Although this plot is a static HTML page, it was created entirely in Python. Bokeh is an excellent visualization library for creating interactive plots with a limited amount of code. I chose Bokeh for this visualization because I've worked with it several times and found development in Bokeh to be extremely fast relative to the quality of output it produces. Querying NeoWs Before you can start querying NASA Open APIs, you will need to create an API key. This is fast and free. Instructions on how to do this can be found at the top of . api.nasa.gov We'll use the library to make GET requests against the NeoWs API. First, make sure requests is installed on your system: requests pip install requests in Python is simple: Making the GET request params = { : today_str, : today_str, : self.api_key} get_request = requests.get(url = self.api_endpoint, params = params) json_resp = get_request.json() 'start_date' 'end_date' 'api_key' now contains a JSON blob from NeoWs like the one above. json_resp We only need a few items from to create our plot, so I extract that information before passing the list of asteroids back to the caller. In this case, we only want the asteroid's name, close approach time, miss distance, diameter, and it's JPL URL. We will append these values as a tuple to our list of asteroids. json_resp miss_miles = neo[ ][ ][ ][ ] diameter_miles = neo[ ][ ][ ] url = neo[ ] asteroid_list.append((name, close_approach_epoch, miss_miles, diameter_miles, url)) 'close_approach_data' 0 'miss_distance' 'miles' 'estimated_diameter' 'miles' 'estimated_diameter_max' 'nasa_jpl_url' Note that the approach date field is in . I use to convert it to UTC time. Install Astropy: BDT time Astropy pip install astropy And then before appending the data to our list: convert BDT to UTC close_approach_epoch = datetime.datetime.strptime(neo[ ][ ][ ], ) close_approach_epoch = Time(close_approach_epoch, scale= ) close_approach_epoch = str(close_approach_epoch.tt) 'close_approach_data' 0 'close_approach_date_full' '%Y-%b-%d %H:%M' 'tdb' Plotting with Bokeh Now that we have our list of tuples of asteroid data, we can create our visualization. First install Bokeh: pip install bokeh Bokeh has a lot of available. Even after working with Bokeh a few times, I still find it helpful to skim through the examples to find the style of plot I would like to create. I then use that code as a starting point. great examples In this case, I started with the example and modified from there. The final code looks quite a bit different, but I do think the example code saved time that would otherwise have been spent Googling things I've forgotten. color scatter Our begins by setting up our data sources: plotting code names = [(name + .format(dia) + ) (name, miss_time, miss_dist, dia, url) neos_list] names.append( ) x = [datetime.datetime.strptime(miss_time[ : ], ) (name, miss_time, miss_dist, dia, url) neos_list] x.append(datetime.datetime.strptime(self.date_str + , )) y = [float(miss_dist) (name, miss_time, miss_dist, dia, url) neos_list] y.append( ) sizes = [float(dia) (name, miss_time, miss_dist, dia, url) neos_list] radii = [size * size sizes] radii.append( ) urls = [url (name, miss_time, miss_dist, dia, url) neos_list] urls.append( ) colors = [] min_dist = min(y) max_dist = max(y) range_dist = max_dist - min_dist (name, dist) zip(names, y): name == : colors.append( ) dist == min_dist: colors.append( % ( , , )) dist == max_dist: colors.append( % ( , , )) : perc = (dist - min_dist)/range_dist num = int(perc * ) num > : colors.append( % ( , num , )) : colors.append( % ( -num, , )) source = ColumnDataSource(data=dict(hours=x, distance=y, names=names, radii=radii, colors=colors, url=urls)) : def plot_asteroids (self, neos_list:list) # We will label each circle on our plot with the NEO name and it's diameter " {:.2f}" " M wide" for in 'Moon' # We will add the moon to our plot to help give a sense of scale # Drop the nanoseconds we don't need off the end of the timestamps 0 -7 '%Y-%m-%d %H:%M:%S' for in ' 04:00' '%Y-%m-%d %H:%M' # We'll put the moon at 4 hours # Distance from Earth will go along the Y axis for in 238900 # The moon is 238,900 from Earth # Let's represent each NEO's relative size with the diameter of each circle # Since most NEOs are less than a mile wide, we will need to scale them by a factor of 1e7 # to see them on our plot for in 1e7 for in 1e6 # This is an arbitrary size, since the moon is actually much larger than any of our NEOs # Users will be able to click on each circle to view the NASA's page for each NEO for in 'https://moon.nasa.gov/' # Moon website! # Let's make the NEOs coming close to Earth red and the # ones farthest from Earth green for in if 'Moon' '#0EBFE9' # Let's make the moon blue so that # it's clear it's different from the NEOs elif "#%02x%02x%02x" 255 0 0 elif "#%02x%02x%02x" 0 255 0 else 500 if 255 "#%02x%02x%02x" 0 -255 0 else "#%02x%02x%02x" 255 0 0 # Create the ColumnDataSource that we will use for plotting and creating labels The list provides the color for each of our circles. The asteroids with smaller miss distances are shades of red and the ones with further miss distances are shades of green. Note that this is all relative to each other; the closest asteroid in the list is set to red regardless of its absolute miss distance. colors Bokeh does provide for colorizing plots. I found that in my case the auto-magic behind the pallettes colorized my circles by radius rather than Y-axis value, so I constructed the colors list myself to achieve the effect I wanted. built-in pallettes After constructing each list, I wrapped all the data in a . It's not required to do this; you can pass the data to Bokeh directly for plotting. However, the provides data mapping that drives a lot of Bokeh's features. In this case, the ColumnDataSource allows us to construct all the labels for our circles with a single call: ColumnDataSource ColumnDataSource labels = LabelSet(x= , y= , text= , source=source, text_font_size= ) 'hours' 'distance' 'names' '8pt' refers to our ColumnDataSource variable defined above. source=source source It also allows us to set up a that will open each asteroid's JPL link when a user clicks on it: TapTool taptool = p.select(type=TapTool) taptool.callback = OpenURL(url= ) # Add TapTool call back that will open a new tab with our NEO URL on a click "@url" refers to the "url" field in our ColumnDataSource. "@url" Bokeh allows us to add some on our chart. I used this feature to credit the source of our data and make an explanatory note about the moon: annotations citation = Label(x= , y= , x_units= , y_units= , text= , render_mode= , border_line_color= , border_line_alpha= , background_fill_color= , background_fill_alpha= ) max_size = max(sizes) scale = .format( /max_size) moon_note = Label(x= , y= , x_units= , y_units= , text= + scale + , render_mode= , border_line_color= , border_line_alpha= , background_fill_color= , background_fill_alpha= , text_font_size= ) # Let's label each NEO to make our plot more meaningful 850 70 'screen' 'screen' 'Data From NASA NeoW API' 'css' 'black' 0.6 'white' 0.6 # Let's make a note comparing the moon's real diameter to the largest NEO on this plot " {:.2f}" 2158.8 # Moon is 2,158.8 miles in diameter 150 30 'screen' 'screen' 'Moon diameter not to scale; it is ' 'x larger than largest NEO on this plot.' 'css' 'black' 0.6 'white' 0.6 "8pt" With these components in place, we can construct our output file and display our plot. output_file( , title= , mode= ) TOOLS = p = figure(tools=TOOLS, x_axis_type= , plot_width= , height= , x_axis_label= , y_axis_label= , title=self.plot_title) p.circle(x= , y= , source=source, radius= , fill_color= , fill_alpha= , line_color= ) labels = LabelSet(x= , y= , text= , source=source, text_font_size= ) p.add_layout(labels) p.add_layout(citation) p.add_layout(moon_note) taptool = p.select(type=TapTool) taptool.callback = OpenURL(url= ) show(p) # Output our plot to a static HTML file "neos_today.html" "NEOs Demo" "cdn" # Set up our plots "pan,wheel_zoom,box_zoom,reset,box_select,lasso_select,tap" "datetime" 1250 650 "Hours After Midnight" "Miles From Earth" "hours" "distance" "radii" "colors" 0.6 None 'hours' 'distance' 'names' '8pt' # Add TapTool call back that will open a new tab with our NEO URL on a click "@url" # Display the plot in a browser defines our static HTML output file. The call will display this file in a browser and can be omitted if you don't wish to display your plot immediately. output_file show refers to various interactive user tools Bokeh provides, such as zooming and panning tools. They appear to the left of my plot (the display location of tools if you wish) and allow users to explore the plot by adjusting it in various ways. TOOLS can be adjusted Sharing your visualization Our output is a static HTML file. I'm using a public S3 bucket to make my example chart available online. I could also include it on another website, or share it via email. Taking this example further Bokeh does for building apps that involve periodic updates to plotted data. I've used Bokeh Server several times and found it easy to use, but not appropriate for embedding Bokeh into other more complex applications. provide a server im plementation Nonetheless, an interesting extension of this project would be to build a simple app that updates asteroid data daily and posts updated plots to a website or S3 bucket. I also wondering about creating a version of this plot that doesn't scale the size of the asteroids up, but instead uses animation to zoom in on each asteroid, providing a better sense of scale in regards to the asteroids' true sizes. Final thoughts This project is a starting point for further exploration into available NASA APIs. Plotting data with Bokeh is the easy part; the limiting factor for most of us will be understanding the NASA data itself. I look forward to putting in a little extra research on some of the more accessible APIs to see what I can learn and build!
