NASA ADS SDKs & Libraries: Python, R, & Community Support

SDKs overview

The NASA Astrophysics Data System (ADS) provides several software development kits (SDKs) and libraries to enable programmatic access to its vast collection of astronomical and astrophysical literature. These tools are designed to streamline the process of querying the ADS database, retrieving publication metadata, and performing citation analysis directly from code. The primary interface for these SDKs is the NASA ADS API, which offers search and data retrieval functionalities.

The ecosystem includes officially supported libraries, particularly for Python and R, alongside various community-contributed projects that extend functionality or provide integrations with other scientific tools. These SDKs abstract the underlying HTTP requests and JSON parsing required for direct API interaction, allowing researchers and developers to focus on data utilization rather than low-level API mechanics. For a comprehensive understanding of the API's capabilities, developers can consult the NASA ADS API reference documentation.

Official SDKs by language

NASA ADS officially supports SDKs for Python and R, which are widely used languages in scientific computing and data analysis. These libraries are maintained by the ADS team and are recommended for reliable and up-to-date interaction with the ADS API.

Python SDK

The official Python SDK for NASA ADS, named ads, provides a high-level interface for interacting with the ADS API. It supports functionalities such as searching for articles, retrieving detailed metadata, accessing citation information, and managing private libraries. The Python SDK simplifies authentication and pagination, common requirements when working with APIs that return large datasets. Developers can find detailed usage examples and API specifics in the Python client documentation.

R SDK

For users of the R programming language, the official ads package offers similar capabilities to its Python counterpart. It allows R users to perform searches, retrieve bibliographic data, and integrate ADS data into their R-based analytical workflows. The R SDK is particularly useful for researchers who conduct statistical analysis and visualization within the R environment. The R ADS package on CRAN provides further details and installation instructions.

Installation

Installing the official NASA ADS SDKs is typically straightforward, leveraging standard package managers for Python and R.

Python Installation

To install the Python ads SDK, use pip, the Python package installer. Ensure you have a recent version of Python and pip installed.

pip install ads

After installation, you will need to configure your NASA ADS API key. This key authenticates your requests and grants access to the API. It can be set as an environment variable (ADS_API_TOKEN) or passed directly in your script. For persistent configuration, creating a ~/.ads/config.cfg file with your API token is recommended.

[ads]
dev_key = YOUR_ADS_API_TOKEN

R Installation

For R users, the ads package can be installed directly from CRAN (Comprehensive R Archive Network).

install.packages("ads")

Similar to the Python SDK, you will need to configure your API key. This is typically done within your R session using Sys.setenv() or by placing the key in an environment file that R can read.

Quickstart example

The following examples demonstrate basic usage of the official Python and R SDKs to perform a simple search query.

Python Quickstart

This Python example searches for articles by 'Edwin Hubble' published in 'Nature'.

import ads

# Ensure your API token is configured (e.g., via ~/.ads/config.cfg or environment variable)
# ads.config.token = "YOUR_ADS_API_TOKEN" # Uncomment and set if not configured globally

# Search for articles by Edwin Hubble in Nature
articles = ads.SearchQuery(q="author:\"Hubble, E.\" journal:Nature", fl=['id', 'title', 'author', 'year'])

print(f"Found {articles.num_pages} pages of results, total {articles.p_total} articles.")

for article in articles.get_results():
    print(f"ID: {article.id}")
    print(f"Title: {article.title[0] if article.title else 'N/A'}")
    print(f"Authors: {', '.join(article.author) if article.author else 'N/A'}")
    print(f"Year: {article.year}")
    print("---------------------")

R Quickstart

This R example performs a similar search for articles by 'Edwin Hubble' in 'Nature'.

# Install and load the ads package
# install.packages("ads") # Uncomment if not already installed
library(ads)

# Ensure your API token is configured (e.g., Sys.setenv(ADS_API_TOKEN="YOUR_ADS_API_TOKEN"))

# Search for articles by Edwin Hubble in Nature
# The 'fl' parameter specifies which fields to return
results <- search_articles(query = "author:\"Hubble, E.\" journal:Nature", fl = c('id', 'title', 'author', 'year'))

# Print the results
if (length(results) > 0) {
  cat(paste0("Found ", length(results), " articles.\n"))
  for (i in seq_along(results)) {
    article <- results[[i]]
    cat(paste0("ID: ", article$id, "\n"))
    cat(paste0("Title: ", article$title, "\n"))
    cat(paste0("Authors: ", paste(article$author, collapse = ", "), "\n"))
    cat(paste0("Year: ", article$year, "\n"))
    cat("---------------------\n")
  }
} else {
  cat("No articles found.\n")
}

Community libraries

Beyond the official SDKs, the NASA ADS community has developed various libraries and tools that integrate with or extend the functionality of the ADS API. These community projects often cater to specific use cases, integrate with other astronomical software, or provide alternative interfaces.

Astropy Integration

One notable integration point is with Astropy, a core Python package for astronomy. While Astropy itself does not directly include an ADS SDK, its ecosystem and affiliated packages often leverage the ADS API for data discovery and metadata retrieval. For example, tools within the Astropy community might use the official Python ads library to fetch bibliographic data for astronomical objects or datasets, then process that information using Astropy's data structures and utilities.

Other Language Bindings and Tools

While Python and R have official SDKs, developers in other languages may create their own wrappers or direct API clients. These might include:

• Julia packages: Authors may develop Julia packages for researchers who prefer this language for scientific computing, often leveraging Julia's capabilities for high-performance numerical analysis.
• Web-based tools: JavaScript libraries or frameworks might be used to build interactive web applications that query the ADS API for real-time data display or search interfaces.
• Workflow orchestrators: Tools like Tray.io or custom scripts might use the ADS API to automate research workflows, such as automatically tracking new publications related to specific topics or authors.

When considering community libraries, it is important to verify their maintenance status, documentation, and compatibility with the latest ADS API specifications. While these libraries can offer flexibility, official SDKs generally provide the most stable and supported means of interaction.