search

adsabs / export_service

Export service to output ADS records with various formats including BibTex, AASTex, and multiple tagged and xml options
MIT License
3 stars 5 forks source link

readme

Build Status Coverage Status

ADS Export Service

Short Summary

This microservice exports ADS records with various formats including BibTex, AASTex, and multiple fielded and xml options.

Setup (recommended)

$ virtualenv python
$ source python/bin/activate
$ pip install -r requirements.txt
$ pip install -r dev-requirements.txt
$ vim local_config.py # edit, edit

Testing

On your desktop run:

$ py.test

API

POST a request:

To get e.g. BibTeX for a set of records you do a POST request to the endpoint

https://api.adsabs.harvard.edu/v1/export/bibtex

within the POST header payload is defined as

{"bibcode":["<bibcode1>","<bibcode2>", ...]}

For example to get the BibTeX for the record with bibcode 2015ApJS..219...21Z, you would do

curl -H "Authorization: Bearer <your API token>" -H "Content-Type: application/json" -X POST -d '{"bibcode":["2015ApJS..219...21Z"]}' https://api.adsabs.harvard.edu/v1/export/bibtex

and the API then responds in JSON with 

{u'msg': u'Retrieved 1 abstracts, starting with number 1.  Total number selected: 1.', u'export': u'@ARTICLE{2015ApJS..219...21Z,\n   author = {{Zhang}, M. and {Fang}, M. and {Wang}, H. and {Sun}, J. and \n\t{Wang}, M. and {Jiang}, Z. and {Anathipindika}, S.},\n    title = "{A Deep Near-infrared Survey toward the Aquila Molecular Cloud. I. Molecular Hydrogen Outflows}",\n  journal = {\\apjs},\narchivePrefix = "arXiv",\n   eprint = {1506.08372},\n primaryClass = "astro-ph.SR",\n keywords = {infrared: ISM, ISM: jets and outflows, shock waves, stars: formation, stars: winds, outflows},\n     year = 2015,\n    month = aug,\n   volume = 219,\n      eid = {21},\n    pages = {21},\n      doi = {10.1088/0067-0049/219/2/21},\n   adsurl = {http://adsabs.harvard.edu/abs/2015ApJS..219...21Z},\n  adsnote = {Provided by the SAO/NASA Astrophysics Data System}\n}\n\n'}

Note that there is an optional parameter sort for sorting the records from solr. The default sort option (if omitted) is by date desc, bibcode desc. For example

curl -H "Authorization: Bearer <your API token>" -H "Content-Type: application/json" -X POST -d '{"bibcode":["2015ApJS..219...21Z", "2018AAS...23221409A"], "sort":"bibcode desc"}' https://api.adsabs.harvard.edu/v1/export/bibtex

To return the records in the exact order of input bibcode list, set sort to no sort.

1. For the following endpoints output is in tagged format:

Note that for endpoints /bibtex and /bibtexabs optional parameters maxauthor, authorcutoff, keyformat and journalformat can be passed in.

2. For the following endpoints output is in xml format:

Note that for endpoint /rss an optional parameter link can be passed in. link is the query url that generated the bibcodes.

For example querying ADS Bumblebee for

author:"accomazzi" and year:2018

at the end of March 2018, returns the following 4 bibcodes, and generates the url as specified below: 

{"bibcode":["2018arXiv180303598K","2018arXiv180101021FB","2018AAS...23136217A","2018AAS...23130709A"], "link":"https://ui.adsabs.harvard.edu/#search/q=author%3A%22accomazzi%22%20and%20year%3A2018&sort=date%20desc%2C%20bibcode%20desc"}

which can be passed as payload to /rss endpoint.

3. For the following Citation Style Language Format endpoints output is in latex format:

Note that for the endpoints /aastex there is an optional parameter journalformat which allows user to decide on the format of journal name. 1 indicates to use AASTeX macros if there are any (default), otherwise full journal name is exported. 2 means use journal abbreviations and 3 means use full journal name.

4. For the following Citation Style Language Format endpoints output is in text format:
5. Using the /csl endpoint for Citation Style Language Formats:

The /csl endpoint allows various citation style language (CSL) and output formats to be defined in the payload as follows:

{"bibcode":["1980ApJS...44..137K","1980ApJS...44..489B"], "style":"", "format":"", "sort":"date desc, bibcode, desc"}

The style parameter can be any of the CSL formats listed in sections 3 and 4 (e.g., aastex, icarus, mnras, soph, aspc, apsj, ieee, agu, gsa, ams). The format specifies the output type: 1 (Unicode), 2 (HTML), or 3 (LaTeX). Additionally, there is an optional journalformat parameter for certain styles (aastex, aspc, and aasj) to specify the journal name format, with values 1 (AASTeX macros, default), 2 (journal abbreviations), or 3 (full journal name).

Note that, as mentioned above, all the CSL formats can also be accessed through their dedicated endpoints, as listed earlier, using a payload like:

{"bibcode":["1980ApJS...44..137K","1980ApJS...44..489B"], "sort":"date desc, bibcode, desc"}
6. For endpoint /custom define payload as:
{"bibcode":["1980ApJS...44..137K","1980ApJS...44..489B"], "format":"%ZEncoding:latex%ZLinelength:0\bibitem[%4m(%Y)]{%R} %5.3l\ %Y, %j, %V, %p.\n"}

GET a request:

GET endpoints are similar to the POSTS endpoints. The curl command has the following syntax:

curl -H "Authorization: Bearer <your API token>" <endpoint>/<bibcode>`

To Convert a Classic Custom Format to the Current Custom Format:

curl -H "Authorization: Bearer <your API token>" -H "Content-Type: application/json" -X POST -d <payload> <endpoint>

where <endpoint> is /convert and <payload> is formatted as: {"format":}

For example:

curl -H "Authorization: Bearer <your API token>" -H "Content-Type: application/json" -X POST -d '{"format":"\\\\bibitem[%\\2m%(y)]\\{%za1%y} %\\8l %\\Y,%\\j,%\\V,%\\p"}' https://api.adsabs.harvard.edu/v1/export/convert

Limiting number of authors and affilations from the UI

A new optional parameter, authorlimit, has been introduced to limit the number of authors and their affiliations returned in exported records. This parameter addresses the growing issue of excessively large author lists, which are becoming increasingly common, with some papers featuring thousands of authors.

The authorlimit parameter specifies the maximum number of authors and affiliations to retrieve from Solr and format in the service.

This parameter will be utilized in the ADS UI. However, when using the API, it is optional. If omitted, the service will return all authors and affiliations.

{"bibcode": ["1980ApJS...44..137K", "1980ApJS...44..489B"], "authorlimit": 500}

To retrieve all records without this limit using the API, you can use the provided script: https://github.com/adsabs/export_service/blob/master/export_with_api.py.

Maintainers

Golnaz, Edwin