ads Python Module

The ads package uses lazy loading for attributes. If you access an attribute that was not included in the initial API request (e.g., citation_count), the package will trigger a new network request for every single article in your loop. This can lead to $N+1$ requests, quickly exhausting your rate limit.

To prevent this, explicitly request the required fields using the fl (field list) parameter in your SearchQuery. This ensures all data is fetched in a single request ($N=1$).

import ads

# BAD: Triggers a new request for every paper to get citation_count
q_bad = ads.SearchQuery(q='star')
for paper in q_bad:
    print(paper.citation_count)

# GOOD: Requests citation_count upfront in the initial call
q_good = ads.SearchQuery(q='star', fl=['id', 'bibcode', 'title', 'citation_count'])
for paper in q_good:
    print(paper.citation_count)

To perform a basic search using the ads library, configure your API token, initialize a SearchQuery with your search parameters (such as q for the query and sort for the sorting criteria), and iterate over the resulting paper objects. Each paper object provides access to metadata like title.

import ads
ads.config.token = 'secret token'

papers = ads.SearchQuery(q="supernova", sort="citation_count")
for paper in papers:
    print(paper.title[0])

To avoid hitting real API rate limits while developing or prototyping your code, you can use the ads.sandbox module. This provides mocked responses instead of accessing the live API.

To switch from sandbox to production, simply change your import from import ads.sandbox as ads to import ads.

# Prototyping with mocked responses
import ads.sandbox as ads

q = ads.SearchQuery(q='star')
for paper in q:
    print(paper.title)

# Switch to live API for production
# import ads

To use the ads package, follow these steps:

1. Obtain an API Key: Sign up at https://ui.adsabs.harvard.edu, go to account settings, and generate a new API token.
2. Configure Authentication: Save your API key in one of two ways:
   • Save it to a file at ~/.ads/dev_key.
   • Set it as an environment variable named ADS_DEV_KEY.
   • Alternatively, you can set it programmatically using ads.config.token = 'your_token'.
3. Install via pip:

   pip install ads

Before making requests to NASA's ADS, you must provide your API token. This is done by setting the token attribute on the ads.config object.

import ads
ads.config.token = 'your_api_token_here'

To install the ads library in editable mode along with its test dependencies, use the following command:

pip install -e . "ads[tests]"

You can track your remaining API quota using the get_ratelimits() method on the query response or by using the ads.RateLimits helper.

Example using query response:

q.response.get_ratelimits()

Example using RateLimits helper:

r = ads.RateLimits('SearchQuery')
r.limits

import ads

q = ads.SearchQuery(q='star')
# ... execute query ...
print(q.response.get_ratelimits())

# Or using the helper
r = ads.RateLimits('SearchQuery')
print(r.limits)

Every search result is an ads.Article object. These objects contain metadata about the paper and provide several useful attributes and methods.

Common attributes include:

• title, abstract, pubdate, year, volume, issue, page
• author, aff (affiliation), id, bibcode, bibstem
• citation_count, citation (to build citation trees)
• keywords, metrics, bibtex

Methods like build_citation_tree() and build_reference_tree() are also available.

import ads

# Assuming 'papers' is a SearchQuery result
first_paper = papers[0]

print(first_paper.title)
print(first_paper.author)
print(first_paper.citation_count)