API_documentation_UNIXshell/Journals_API.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Journals Search Requests\n",
        "The ADS maintains a database of summary information about the publications we index -- the Journals database (JournalsDB).  It includes information that the ADS uses for internal content management, but that is also useful for librarians and other content managers to know about how specific titles are classified and what the ADS' holdings are for individual titles and volumes.  This notebook explains how to retrieve information from the JournalsDB using the Journals API.\n",
        "\n",
        "The base URL for journals queries is `https://api.adsabs.harvard.edu/v1/journals/<endpoint>`. \n",
        "\n",
        "where the allowed `<endpoint>` values are:\n",
        "* `/summary/<bibstem>`: generate a summary of information about the publication having `<bibstem>`; note here and elsewhere in this document that bibstem is case-sensitive (`ApJ` is a valid bibstem, `apj` is not)\n",
        "* `/journal/<search text>`:generate a list of bibstems whose journal name and abbreviation data contain `<search text>`; `<search text>` must be url-encoded text\n", 
        "* `/refsource/<bibstem>`: generate a list of citation data sources on a per volume basis for a given `<bibstem>`\n",
        "* `/holdings/<bibstem>/<volume>`: generate a list of available electronic sources for a given `<bibstem>/<volume>`\n",
        "* `/issn/<search text>`: return the ADS bibstem for the journal having an ISSN identifier that matches `<search text>`\n",
        "\n",
        "All queries to the API must include an HTTP header that specifies your API access token, e.g.\n",
        "\n",
        "`curl -H 'Authorization: Bearer <token>' ...`\n",
        "\n",
        "In the examples below, `<token>` is your personal API access token as described in the top-level [README](https://github.com/adsabs/adsabs-dev-api/blob/master/README.md).\n",
        "\n",
        "Notes:\n",
        "* The information in the JournalsDB is being actively curated and expanded, and records may be added or modified without notice.  For questions about results, please contact adshelp@cfa.harvard.edu.\n",
        "* All examples use the default HTTP method GET.\n",
        "* the API examples in this notebook generally 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)."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### `/summary/<bibstem>`\n",
        "Generate a summary of information about the publication having `<bibstem>`\n",
        "\n",
        "*Return data*: output is JSON\n",
        "* `summary`\n",
        "  * `abbrev` (list, text): names and abbreviations for the Title found in our metadata holdings\n",
        "  * `idents` (list, dict): identifiers for the Title (currently consist of ISSN (print and electronic) and Crossref set numbers)\n",
        "    * `\"id_type\"` (one of \"ISSN_print\", \"ISSN_electronic\", or \"Crossref\")\n",
        "    * `\"id_value\"`\n",
        "  * `master` (dict): canonical record for Title (Note: some fields are missing/incomplete)\n",
        "    * `bibstem` (text, case-sensitive): the ADS bibstem\n",
        "    * `collection` (text): ADS collection that includes Title\n",
        "    * `defunct` (boolean): `True` if publication of Title has ceased\n",
        "    * `journal_name` (text): canonical name for Title used by ADS\n",
        "    * `multilingual` (boolean): `True` if Title publishes papers in two or more languages in a single volume\n",
        "    * `not_indexed` (boolean): ADS internal field, used for retired or reassigned bibstems (e.g. `ApJL`)\n",
        "    * `notes` (text): curator and other notes about the Title\n",
        "    * `primary_language` (text): ISO 639-1 code for Title fulltext language\n",
        "    * `pubtype` (text): one of \"Journal\", \"Conf. Proc.\", \"Monograph\", \"Book\", \"Software\", \"Other\"\n",
        "    * `refereed` (text): one of \"yes\", \"no\", \"na\", \"partial\"\n",
        "  * `names` (list, dict): native-language and transliterated names for non-English Titles\n",
        "    * `name_english_translated` (text): Title name translated into English\n",
        "    * `title_language` (text): ISO 639-1 code for the Title's original language\n",
        "    * `name_native_language` (text): Unicode rendering of the Title in `title_language`\n",
        "    * `name_normalized` (text): Title `name_native_language` transliterated into English\n",
        "  * `pubhist` (list, dict): current and historical information about Title and its publisher(s); when possible, Titles having multiple publishers during their history will have multiple entries, each with the appropriate date and volume ranges\n",
        "    * `publisher` (text): Publisher name or acronym\n",
        "    * `title` (dict): Summary publication information\n",
        "      * `complete` (text): `Y` if ADS index the complete run of this publication\n",
        "      * `notes` (text): Curator or other notes\n",
        "      * `successor_masterid` (text): identifier of successor Title, if publication ceased and continued under a different name\n",
        "      * `vol_end` (text): last or most recent available volume from Publisher in ADS records (currently active Titles will have `-`)\n",
        "      * `vol_start` (text): first available volume from Publisher in ADS records\n",
        "      * `year_end` (integer): most recent available year from Publisher in ADS records\n",
        "      * `year_start` (integer): first available year from Publisher in ADS records\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "{\n",
            "    \"summary\": {\n",
            "        \"master\": {\n",
            "            \"bibstem\": \"ApJ\",\n",
            "            \"journal_name\": \"The Astrophysical Journal\",\n",
            "            \"primary_language\": \"en\",\n",
            "            \"multilingual\": false,\n",
            "            \"defunct\": false,\n",
            "            \"pubtype\": \"Journal\",\n",
            "            \"refereed\": \"yes\",\n",
            "            \"collection\": null,\n",
            "            \"notes\": null,\n",
            "            \"not_indexed\": false\n",
            "        },\n",
            "        \"idents\": [\n",
            "            {\n",
            "                \"id_type\": \"ISSN_print\",\n",
            "                \"id_value\": \"0004-637X\"\n",
            "            },\n",
            "            {\n",
            "                \"id_type\": \"Crossref\",\n",
            "                \"id_value\": \"4876\",\n",
            "            {\n",
            "                \"id_type\": \"ISSN_electronic\",\n",
            "                \"id_value\": \"1538-4357\"\n",
            "            }\n",
            "        ],\n",
            "        \"abbrev\": [\n",
            "            \"ASTROPHYSICAL JOURNAL\",\n",
            "            \"Ap. J.\",\n",
            "            \"Ap. J. Lett.\",\n",
            "            \"ApJ Letters\",\n",
            "            \"ApJL\",\n",
            "            \"Astrophy. J.\",\n",
            "            \"Astrophys J\",\n",
            "            \"Astrophys J Lett Ed\",\n",
            "            \"Astrophys J.\",\n",
            "            \"Astrophys. J\",\n",
            "            \"Astrophys. J.\",\n",
            "            \"Astrophys. J. :\",\n",
            "            \"Astrophys. J. Let.\",\n",
            "            \"Astrophys. J. Lett.\",\n",
            "            \"Astrophys. J. Letters\",\n",
            "            \"Astrophys. Journ.\",\n",
            "            \"Astrophysic. J.\",\n",
            "            \"Astrophysical J.\",\n",
            "            \"Astrophysical J. US\",\n",
            "            \"Astrophysical Jour.\",\n",
            "            \"Astrophysical Journal Letters\",\n",
            "            \"Astrosphys. J.\",\n",
            "            \"J. Astrophys\",\n",
            "        ],\n",
            "        \"pubhist\": [\n",
            "            {\n",
            "                \"publisher\": \"IOP\",\n",
            "                \"title\": {\n",
            "                    \"year_start\": 1895,\n",
            "                    \"year_end\": null,\n",
            "                    \"vol_start\": \"1\",\n",
            "                    \"vol_end\": \"-\",\n",
            "                    \"complete\": \"Y\",\n",
            "                    \"successor_masterid\": null,\n",
            "                    \"notes\": \"https:\/\/iopscience.iop.org\/journal\/0004-637X\"\n",
            "                }\n",
            "            }\n",
            "        ],\n",
            "        \"names\": []\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",
            "100  1104  100  1104    0     0   5132      0 --:--:-- --:--:-- --:--:--  5385\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "token=\"your-token-here\"\n",
        "# note: add | python -m json.tool to the end of the request to print the response in a more readable format\n",
        "curl -H \"Authorization: Bearer $token\" https:\/\/api.adsabs.harvard.edu\/v1\/journals\/summary\/PASJ | python3 -m json.tool"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### `/journal/<search text>`\n",
        "Generate a list of bibstems whose journal name and abbreviation data contain `<search text>`\n",
        "\n",
        "*Return data*: output is JSON\n",
        "* `journal` (list, dict): list of matching name-bibstem pairs whose names match `<search text>`\n",
        "  * `bibstem` (text, case-sensitive): ADS bibstem for Title\n",
        "  * `name` (text): name of Title matching `<search text>`\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "{\n",
            "    \"journal\": [\n",
            "        {\n",
            "            \"bibstem\": \"OAJ\",\n",
            "            \"name\": \"The Open Astronomy Journal\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"AJ\",\n",
            "            \"name\": \"The Astronomical Journal\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"JRASC\",\n",
            "            \"name\": \"Journal of the Royal Astronomical Society of Canada\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"AJS\",\n",
            "            \"name\": \"The Astronomical Journal Supplement\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"CAPJ\",\n",
            "            \"name\": \"Communicating Astronomy with the Public Journal\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"JBAA\",\n",
            "            \"name\": \"Journal of the British Astronomical Association\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"BlgAJ\",\n",
            "            \"name\": \"Bulgarian Astronomical Journal\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"PAIJ\",\n",
            "            \"name\": \"Physics &amp; Astronomy International Journal\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"RadA\",\n",
            "            \"name\": \"Radio Astronomy: Journal of the Society of Amateur Radio Astronomers,\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"2010AIPC.1283\",\n",
            "            \"name\": \"Mathematics and Astronomy: A Joint Long Journey\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"IrAJ\",\n",
            "            \"name\": \"Irish Astronomical Journal\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"IrAJS\",\n",
            "            \"name\": \"Irish Astronomical Journal Supplement\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"RoAJ\",\n",
            "            \"name\": \"Romanian Astronomical Journal\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"AEdJ\",\n",
            "            \"name\": \"Astronomy Education Journal\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"SerAJ\",\n",
            "            \"name\": \"Serbian Astronomical Journal\"\n",
            "        },\n",
            "        {\n",
            "            \"bibstem\": \"AzAJ\",\n",
            "            \"name\": \"Azerbaijani Astronomical Journal\"\n",
            "        }\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",
            "100  1151  100  1151    0     0   3905      0 --:--:-- --:--:-- --:--:--  4052\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "token=\"your-token-here\"\n",
        "curl -H \"Authorization: Bearer $token\" https:\/\/api.adsabs.harvard.edu\/v1\/journals\/journal\/Astronom%20Jour | python3 -m json.tool\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### `/refsource/<bibstem>`\n",
        "Generate a list of citation data sources on a per volume basis for a given `<bibstem>`\n",
        "\n",
        "*Return data*: output is JSON\n",
        "* `refsource` (dict): list of volume, year, and reference sources in ADS holdings for a given bibstem\n",
        "  *  `bibstem` (text, case-sensitive): ADS bibstem for a given Title\n",
        "  *  `volumes` (list, dict): refsource data for individual volumes of Title\n",
        "    * `volume` (text): Volume number\n",
        "    * `year` (text): Year the volume was published\n",
        "    * `refsources` (dict): number of papers with reference data originating from each `<data source>` in the volume\n",
        "      * `<data source>` (text): Origin of references, can be one or more of: [`AUTHOR`, `ISI`, `CROSSREF`, `OCR`, `PUBLISHER` or `OTHER`]\n",
        "      * `<number of papers>` (integer): count of records having reference data sourced from `<data source>`; if this number is the same as the number of papers in the volume, we have complete references from that source for the Title/volume; `PUBLISHER` data should be considered the most definitive.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 3,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "{\n",
            "    \"refsource\": {\n",
            "        \"bibstem\": \"ARA&A\",\n",
            "        \"volumes\": [\n",
            "            {\n",
            "                \"volume\": \"1\",\n",
            "                \"year\": \"1963\",\n",
            "                \"refsources\": {\n",
            "                    \"OCR\": 14,\n",
            "                    \"AUTHOR\": 8\n",
            "                }\n",
            "            },\n",
            "            {\n",
            "                \"volume\": \"2\",\n",
            "                \"year\": \"1964\",\n",
            "                \"refsources\": {\n",
            "                    \"OCR\": 17,\n",
            "                    \"AUTHOR\": 12\n",
            "                }\n",
            "            },\n",
            "            {\n",
            "                \"volume\": \"3\",\n",
            "                \"year\": \"1965\",\n",
            "                \"refsources\": {\n",
            "                    \"OCR\": 13,\n",
            "                    \"AUTHOR\": 5,\n",
            "                    \"OTHER\": 1\n",
            "                }\n",
            "            },\n",
            "            {\n",
            "                \"rows-omitted\": \"[...]\",\n",
            "            },\n",
            "            {\n",
            "                \"volume\": \"57\",\n",
            "                \"year\": \"2019\",\n",
            "                \"refsources\": {\n",
            "                    \"CROSSREF\": 15,\n",
            "                    \"AUTHOR\": 1\n",
            "                }\n",
            "            },\n",
            "            {\n",
            "                \"volume\": \"58\",\n",
            "                \"year\": \"2020\",\n",
            "                \"refsources\": {\n",
            "                    \"CROSSREF\": 16\n",
            "                }\n",
            "            },\n",
            "            {\n",
            "                \"volume\": \"59\",\n",
            "                \"year\": \"2021\",\n",
            "                \"refsources\": {\n",
            "                    \"PUBLISHER\": 11,\n",
            "                    \"AUTHOR\": 2\n",
            "                }\n",
            "            }\n",
            "        ]\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",
            "100  5119  100  5119    0     0  12465      0 --:--:-- --:--:-- --:--:-- 12861\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "token=\"your-token-here\"\n",
        "# note: add | python -m json.tool to the end of the request to print the response in a more readable format\n",
        "curl -H \"Authorization: Bearer $token\" https:\/\/api.adsabs.harvard.edu\/v1\/journals\/refsource\/ARA&A' | python3 -m json.tool"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### `/holdings/<bibstem>/<volume>`\n",
        "Generate a list of available electronic fulltext sources for a given `<bibstem>/<volume>`\n",
        "\n",
        "*Return data*: output is JSON\n",
        "* `bibstem` (text, case-sensitive): ADS bibstem for a given Title\n",
        "* `volume` (text): volume for a given Title (may be alpha-numeric, e.g. `500A`)\n",
        "* `numFound` (integer): Number of records found for Title/volume\n",
        "* `holdings` (list, dict): page number and e-sources for each indexed paper in the volume\n",
        "  * `page` (text): page number or page id\n",
        "  * `esources` (list, text): one or more of [`EPRINT_HTML`, `EPRINT_PDF`, `PUB_HTML`, `PUB_PDF`, `ADS_PDF`, `ADS_SCAN`, `AUTHOR_PDF`, `AUTHOR_HTML`]\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 4,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "{\n",
            "    \"bibstem\": \"ApJS\",\n",
            "    \"volume\": \"257\",\n",
            "    \"numFound\": 71,\n",
            "    \"holdings\": [\n",
            "        {\n",
            "            \"esources\": [\n",
            "                \"EPRINT_HTML\",\n",
            "                \"EPRINT_PDF\",\n",
            "                \"PUB_HTML\",\n",
            "                \"PUB_PDF\"\n",
            "            ],\n",
            "            \"page\": \"1\"\n",
            "        },\n",
            "        {\n",
            "            \"esources\": [\n",
            "                \"EPRINT_HTML\",\n",
            "                \"EPRINT_PDF\",\n",
            "                \"PUB_HTML\",\n",
            "                \"PUB_PDF\"\n",
            "            ],\n",
            "            \"page\": \"2\"\n",
            "        },\n",
            "        {\n",
            "            \"esources\": [\n",
            "                \"EPRINT_HTML\",\n",
            "                \"EPRINT_PDF\",\n",
            "                \"PUB_HTML\",\n",
            "                \"PUB_PDF\"\n",
            "            ],\n",
            "            \"page\": \"3\"\n",
            "        },\n",
            "        {\n",
            "            \"rows-omitted\": \"[...]\"\n",
            "        },\n",
            "        {\n",
            "            \"esources\": [\n",
            "                \"EPRINT_HTML\",\n",
            "                \"EPRINT_PDF\",\n",
            "                \"PUB_HTML\",\n",
            "                \"PUB_PDF\"\n",
            "            ],\n",
            "            \"page\": \"69\"\n",
            "        },\n",
            "        {\n",
            "            \"esources\": [\n",
            "                \"PUB_HTML\",\n",
            "                \"PUB_PDF\"\n",
            "            ],\n",
            "            \"page\": \"70\"\n",
            "        },\n",
            "        {\n",
            "            \"esources\": [\n",
            "                \"PUB_HTML\",\n",
            "                \"PUB_PDF\"\n",
            "            ],\n",
            "            \"page\": \"71\"\n",
            "        }\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",
            "100  5474  100  5474    0     0  14084      0 --:--:-- --:--:-- --:--:-- 14519\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "token=\"your-token-here\"\n",
        "# note: add | python -m json.tool to the end of the request to print the response in a more readable format\n",
        "curl -H 'Authorization: Bearer $token' 'https:\/\/api.adsabs.harvard.edu\/v1\/journals\/holdings\/ApJS\/257' | python3 -m json.tool"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "### `/issn/<search text>`\n",
        "Return the ADS Bibstem and Journal Name having the ISSN `<search text>`\n",
        "\n",
        "*Return data*: output is JSON\n",
        "* `issn` (dict): dict containing bibstem, journal_name, ISSN, and ISSN_type for the journal with ISSN matching `<search text>`\n",
        "  * `ISSN` (text, case-sensitive): ISSN for the matching journal\n",
        "  * `ISSN_type` (text, case-sensitive): Type of ISSN (including `ISSN_print`, `ISSN_electronic`, among other)\n",
        "  * `bibstem` (text, case-sensitive): bibstem for the matching journal\n",
        "  * `journal_name` (text): name of the matching journal\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 5,
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "{\n",
            "    \"issn\": {\n",
            "        \"ISSN\": \"0004-637X\",\n",
            "        \"ISSN_type\": \"ISSN_print\",\n",
            "        \"bibstem\": \"ApJ\",\n",
            "        \"journal_name\": \"The Astrophysical Journal\"\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",
            "100  5474  100  5474    0     0  14084      0 --:--:-- --:--:-- --:--:-- 14519\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "token=\"your-token-here\"\n",
        "# note: add | python -m json.tool to the end of the request to print the response in a more readable format\n",
        "curl -H \"Authorization: Bearer $token\" https:\/\/api.adsabs.harvard.edu\/v1\/journals\/issn\/0004-637X | python3 -m json.tool"
      ]
    }
  ],
  "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
}