Devel

Export_API.ipynb

@@ -0,0 +1,183 @@
+{
+ "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
+}