API_documentation_UNIXshell/Export_API.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Export service\n",
    "This notebook explains how to retrieve data in BibTeX and other formats for one or more bibcodes.\n",
    "\n",
    "The base URL for export queries is:\n",
    "```\n",
    "https://api.adsabs.harvard.edu/v1/export/<format>\n",
    "```\n",
    "\n",
    "where `<format>` should be replaced by the desired export format. For example, to get BibTeX for a set of records, send a request with the POST method to the URL `https://api.adsabs.harvard.edu/v1/export/bibtex`. The following formats are currently supported:\n",
    "* BibTeX (`/bibtex`)\n",
    "* BibTeX ABS (`/bibtexabs`)\n",
    "* ADS (`/ads`)\n",
    "* EndNote (`/endnote`)\n",
    "* ProCite (`/procite`)\n",
    "* RIS (`/ris`)\n",
    "* RefWorks (`/refworks`)\n",
    "* RSS (`/rss`)\n",
    "* MEDLARS (`/medlars`)\n",
    "* DC-XML (`/dcxml`)\n",
    "* REF-XML (`/refxml`)\n",
    "* REFABS-XML (`/refabsxml`)\n",
    "* AASTeX (`/aastex`)\n",
    "* Icarus (`/icarus`)\n",
    "* MNRAS (`/mnras`)\n",
    "* Solar Physics (`/soph`)\n",
    "* VOTable (`/votable`)\n",
    "* Custom format (`/custom`)\n",
    "\n",
    "The POST payload (set via the `-d` flag) should be in JSON format. To indicate the payload format, you must add the following header to your `curl` request: `-H \"Content-Type: application/json\"`. For the export, the payload accepts the following keys: \n",
    "* `bibcode`: **required**; set the value to a list of the bibcodes to export\n",
    "* `sort`: optional; set the value to a combination of the field to sort on (see the Fields section in the Search API notebook), followed by a space plus `asc` or `desc` to indicate ascending or descending order. If the sort order is not specified, the default sort is by date, then by bibcode \n",
    "* `format`: **required when using custom format**; set the value to a string with the [desired formatting codes](http://adsabs.github.io/help/actions/export)\n",
    "\n",
    "For example, for most formats the POST payload would take this format: `{\"bibcode\": [\"<bibcode1>\",\"<bibcode2>\", ...], \"sort\": \"<field> <asc or desc>\"}`. For custom format exports, the POST payload would take this format: `{\"bibcode\": [\"<bibcode1>\",\"<bibcode2>\", ...], \"sort\": \"<field> <asc or desc>\", \"format\": \"<custom format string>\"}`\n",
    "\n",
    "The complete `curl` request should also include your personal API access token, as described in the top-level [README](https://github.com/adsabs/adsabs-dev-api/blob/master/README.md). The complete `curl` request follows this format:\n",
    "```\n",
    "    curl -H \"Authorization: Bearer <your API token>\" -H \"Content-Type: application/json\" https://api.adsabs.harvard.edu/v1/export/<format> -X POST -d '{\"bibcode\":[\"<bibcode1>\",\"<bibcode2>\", ...]}' \n",
    "```\n",
    "\n",
    "Note: the API examples in this notebook assume you're using `curl` statements from the shell command line--you'll see `%%bash` at the top of a cell if its contents should be run in the shell instead of in Python. Guidelines for translating bash `curl` statements into Python can be found in the [converting curl to python notebook](Converting_curl_to_python.ipynb). If you prefer, you can use the unofficial Python package instead; see the top-level [README](https://github.com/adsabs/adsabs-dev-api/blob/master/README.md) for more information."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Examples"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"msg\": \"Retrieved 1 abstracts, starting with number 1.\", \"export\": \"@ARTICLE{2015RaSc...50..916A,\\n       author = {{Ads}, A.~G. and {Bergad{\\\\`a}}, P. and {Regu{\\\\'e}}, J.~R. and {Alsina-\\n        Pag{\\\\`e}s}, R.~M. and {Pijoan}, J.~L. and {Altadill}, D. and\\n        {Badia}, D. and {Graells}, S.},\\n        title = \\\"{Vertical and oblique ionospheric soundings over the long haul HF link\\n        between Antarctica and Spain}\\\",\\n      journal = {Radio Science},\\n     keywords = {VIS, OIS, ionosphere},\\n         year = 2015,\\n        month = Sep,\\n       volume = {50},\\n        pages = {916-930},\\n          doi = {10.1002/2015RS005773},\\n       adsurl = {https://ui.adsabs.harvard.edu/#abs/2015RaSc...50..916A},\\n      adsnote = {Provided by the SAO/NASA Astrophysics Data System}\\n}\\n\\n\"}"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r",
      "100   833  100   798  100    35    798     35  0:00:01 --:--:--  0:00:01  3062\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# get the BibTeX entry for a single bibcode\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/export/bibtex \\\n",
    "    -X POST -d '{\"bibcode\":[\"2015RaSc...50..916A\"]}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"msg\": \"Retrieved 3 abstracts, starting with number 1.\", \"export\": \"\\\\bibitem[Accomazzi, et al.(2000)]{2000A&AS..143...85A} Accomazzi, A., Eichhorn, G., Kurtz, M.~J., et al.\\\\ 2000, Astronomy and Astrophysics Supplement Series, 143, 85.\\n\\\\bibitem[Grant, et al.(2000)]{2000A&AS..143..111G} Grant, C.~S., Accomazzi, A., Eichhorn, G., et al.\\\\ 2000, Astronomy and Astrophysics Supplement Series, 143, 111.\\n\\\\bibitem[Kurtz, et al.(2000)]{2000A&AS..143...41K} Kurtz, M.~J., Eichhorn, G., Accomazzi, A., et al.\\\\ 2000, Astronomy and Astrophysics Supplement Series, 143, 41.\\n\"}"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r",
      "100   684  100   574  100   110    574    110  0:00:01 --:--:--  0:00:01   915\r",
      "100   684  100   574  100   110    574    110  0:00:01 --:--:--  0:00:01   914\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# get the AASTeX entries for multiple bibcodes, sorting by first author\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/export/aastex \\\n",
    "    -X POST \\\n",
    "    -d '{\"bibcode\": [\"2000A&AS..143...41K\", \"2000A&AS..143...85A\", \"2000A&AS..143..111G\"], \"sort\": \"first_author asc\"}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"msg\": \"Retrieved 3 abstracts, starting with number 1.\", \"export\": \"Accomazzi, Eichhorn, Kurtz, Grant \\\\& Murray 2000\\nGrant, Accomazzi, Eichhorn, Kurtz \\\\& Murray 2000\\nKurtz, Eichhorn, Accomazzi, Grant, Murray \\\\& Watson 2000\\n\\n\"}"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r",
      "100   363  100   234  100   129    234    129  0:00:01 --:--:--  0:00:01  1354\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# same as above, but exported using a custom format\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/export/custom \\\n",
    "    -X POST \\\n",
    "    -d '{\"format\": \"%m %Y\", \"bibcode\": [\"2000A&AS..143...41K\", \"2000A&AS..143...85A\", \"2000A&AS..143..111G\"], \"sort\": \"first_author asc\"}'"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}