ui.adsabs.harvard.edu
Using the ADS API
1. Get an API token. In your new ADS account, click Account > Customize
Settings, then click on API Token in the left sidebar. Click the Generate a new key
button - your API token is the long series of letters and numbers in the box.
Note: you may make up to
5000 regular queries (or
100 “big queries”) a day
2. Choose an access method. There are several ways to make queries using the
API; choose the method that works best for you:
● Command line using curl*
○ Best for: quick queries, learning to create API searches
● Python scripts using the requests* library
○ Best for: creating scripts, easy translation between command line
curl requests and Python
● Python scripts using the unofficial ADS library
○ Best for: creating advanced scripts, efficient memory usage
3. Start searching. Searches using the API rely on building and sending URLs,
similar to what you’d see in your web browser. Syntax varies based on the
access method, but searches with starred (*) access methods need the following:
● Type of call/HTTP method: GET (default), POST, or PUT; check the ADS
API documentation (https://ui.adsabs.harvard.edu/help/api/) to get the
correct method for your type of request
● Your API token, sent as a header (see examples)
● Base URL: https://api.adsabs.harvard.edu/v1
● Endpoint: the part after the base URL, separated with front-slashes. This
varies based on your request, e.g. /search for simple searches
● Query string: for /search requests, the URL-encoded query parameters, e.g.
/query?q={search parameters}
● Example search URL (uses GET method):
https://api.adsabs.harvard.edu/v1/search/query?q=neutron+star
ui.adsabs.harvard.edu
ADS API search examples
● Command line, using curl
curl -H "Authorization: Bearer token"
"https://api.adsabs.harvard.edu/v1/search/query?q=author%3Amart
%C3%ADnez+neutron+star"
curl -H "Authorization: Bearer token"
"https://api.adsabs.harvard.edu/v1/search/query?q=bibstem%3AApJ
%20year%3A2015&sort=citation_count%20desc
● Python, using the requests library
import requests
r=requests.get('https://api.adsabs.harvard.edu/v1/search/query?
q=author%3Amart%C3%ADnez+neutron+star',
headers={'Authorization': 'Bearer token'})
r=requests.get('https://api.adsabs.harvard.edu/v1/search/query?
q=bibstem%3AApJ%20year%3A2015&sort=citation_count%20desc',
headers={'Authorization': 'Bearer token'})
● Andy Casey’s unofficial ADS Python module
import ads
ads.config.token = 'token'
r = ads.SearchQuery(q='author:martinez neutron star')
r = ads.SearchQuery(q='bibstem:ApJ year:2015',
sort="citation_count")
