The Author Data API from Semantic Scholar — 4 operation(s) for author data.
openapi: 3.0.0
info:
title: Academic Graph Author Data API
version: '1.0'
description: "Fetch paper and author data from the Semantic Scholar Academic Graph (S2AG).\n <br><br>\n Some things to note:\n <ul>\n <li>If you are using an API key, it must be set in the header <code>x-api-key</code> (case-sensitive).</li>\n <li>We have two different IDs for a single paper:\n <ul>\n <li><code>paperId</code> - string - The primary way to identify papers when using our website or this API</li>\n <li><code>corpusId</code> - int64 - A second way to identify papers. Our datasets use corpusId when pointing to papers.</li>\n </ul>\n </li>\n <li>Other useful resources<ul>\n <li><a href=\"https://www.semanticscholar.org/product/api\">Overview</a></li>\n <li><a href=\"https://github.com/allenai/s2-folks/\">allenai/s2-folks</a></li>\n <li><a href=\"https://github.com/allenai/s2-folks/blob/main/FAQ.md\">FAQ</a> in allenai/s2folks</li>\n </ul></li>\n "
servers:
- url: https://api.semanticscholar.org/graph/v1
tags:
- name: Author Data
paths:
/author/batch:
post:
summary: Get details for multiple authors at once
operationId: post_graph_get_authors
tags:
- Author Data
description: "* Fields is a single-value string parameter, not a multi-value one.\n* It is a query parameter, not to be submitted in the POST request's body.\n\nIn python:\n\n r = requests.post(\n 'https://api.semanticscholar.org/graph/v1/author/batch',\n params={'fields': 'name,hIndex,citationCount'},\n json={\"ids\":[\"1741101\", \"1780531\"]}\n )\n print(json.dumps(r.json(), indent=2))\n\n [\n {\n \"authorId\": \"1741101\",\n \"name\": \"Oren Etzioni\",\n \"citationCount\": 34803,\n \"hIndex\": 86\n },\n {\n \"authorId\": \"1780531\",\n \"name\": \"Daniel S. Weld\",\n \"citationCount\": 35526,\n \"hIndex\": 89\n }\n ]\n\nOther Examples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/batch</code></li>\n <ul>\n <li><code>{\"ids\":[\"1741101\", \"1780531\", \"48323507\"]}</code></li>\n <li>Returns details for 3 authors.</li>\n <li>Each author returns the field authorId and name if no other fields are specified.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/batch?fields=url,name,paperCount,papers,papers.title,papers.openAccessPdf</code></li>\n <ul>\n <li><code>{\"ids\":[\"1741101\", \"1780531\", \"48323507\"]}</code></li>\n <li>Returns authorID, url, name, paperCount, and list of papers for 3 authors.</li>\n <li>Each paper has its paperID, title, and link if available.</li>\n </ul>\n</ul>\n<br>\nLimitations:\n<ul>\n <li>Can only process 1,000 author ids at a time.</li>\n <li>Can only return up to 10 MB of data at a time.</li>\n</ul>"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorIdList'
responses:
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: List of authors with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorWithPapers'
/author/search:
get:
summary: Search for authors by name
operationId: get_graph_get_author_search
tags:
- Author Data
description: "Specifying <code>papers</code> fields in the request will return all papers linked to each author in the results. Set a <code>limit</code> on the search results to reduce output size and latency.<br><br>\nExamples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/search?query=adam+smith</code></li>\n <ul>\n <li>Returns with total=490, offset=0, next=100, and data is a list of 100 authors.</li>\n <li>Each author has their authorId and name. </li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/search?query=adam+smith&fields=name,url,papers.title,papers.year&limit=5</code></li>\n <ul>\n <li>Returns with total=490, offset=0, next=5, and data is a list of 5 authors.</li>\n <li>Each author has authorId, name, url, and a list of their papers title and year.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/search?query=totalGarbageNonsense</code></li>\n <ul>\n <li>Returns with total = 0, offset=0, and data is a list of 0 author.</li>\n </ul>\n <br>\n Limitations:\n<ul>\n <li>Can only return up to 10 MB of data at a time.</li>\n</ul>"
responses:
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Batch of authors with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorSearchBatch'
/author/{author_id}:
get:
summary: Details about an author
operationId: get_graph_get_author
tags:
- Author Data
description: "Examples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101</code></li>\n <ul>\n <li>Returns the author's authorId and name.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101?fields=url,papers</code></li>\n <ul>\n <li>Returns the author's authorId, url, and list of papers. </li>\n <li>Each paper has its paperId plus its title.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101?fields=url,papers.abstract,papers.authors</code></li>\n <ul>\n <li>Returns the author's authorId, url, and list of papers. </li>\n <li>Each paper has its paperId, abstract, and list of authors.</li>\n <li>In that list of authors, each author has their authorId and name.</li>\n </ul>\n <br>\n Limitations:\n <ul>\n <li>Can only return up to 10 MB of data at a time.</li>\n </ul>\n</ul>"
responses:
'404':
description: Bad paper id
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: Author with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorWithPapers'
/author/{author_id}/papers:
get:
summary: Details about an author's papers
operationId: get_graph_get_author_papers
tags:
- Author Data
description: "Fetch the papers of an author in batches.<br>\nOnly retrieves the most recent 10,000 citations/references for papers belonging to the batch.<br>\nTo retrieve the full set of citations for a paper,\nuse the /paper/{paper_id}/citations endpoint\n<br><br>\nExamples:\n<ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101/papers</code></li>\n <ul>\n <li>Return with offset=0, and data is a list of the first 100 papers.</li>\n <li>Each paper has its paperId and title.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101/papers?fields=url,year,authors&limit=2</code></li>\n <ul>\n <li>Returns with offset=0, next=2, and data is a list of 2 papers.</li>\n <li>Each paper has its paperId, url, year, and list of authors.</li>\n <li>Each author has their authorId and name.</li>\n </ul>\n <li><code>https://api.semanticscholar.org/graph/v1/author/1741101/papers?fields=citations.authors&offset=260</code></li>\n <ul>\n <li>Returns with offset=260, and data is a list of the last 4 papers.</li>\n <li>Each paper has its paperId and a list of citations.</li>\n <li>Each citation has its paperId and a list of authors.</li>\n <li>Each author has their authorId and name.</li>\n </ul>\n</ul>"
responses:
'404':
description: Bad paper id
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'400':
description: Bad query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'200':
description: List of papers with default or requested fields
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorPaperBatch'
components:
schemas:
AuthorIdList:
properties:
ids:
type: array
items:
type: string
example: '1741101'
type: object
AuthorPaperBatch:
properties:
offset:
type: integer
description: Starting position for this batch.
next:
type: integer
description: Starting position of the next batch. Absent if no more data exists.
data:
type: array
items:
title: contents of this batch
allOf:
- $ref: '#/components/schemas/PaperWithLinks'
type: object
Error400:
properties:
error:
type: string
description: "Depending on the case, error message may be any of these:\n<ul>\n <li><code>\"Unrecognized or unsupported fields: [bad1, bad2, etc...]\"</code></li>\n <li><code>\"Unacceptable query params: [badK1=badV1, badK2=badV2, etc...}]\"</code></li>\n <li><code>\"Response would exceed maximum size....\"</code></li>\n <ul><li>This error will occur when the response exceeds 10 MB. Suggestions to either break the request into smaller batches, or make use of the limit and offset features will be presented.</li></ul>\n <li>A custom message string</li></ul>"
example: 'Unrecognized or unsupported fields: [author.creditCardNumber, garbage]'
type: object
PaperInfo:
properties:
paperId:
type: string
description: Semantic Scholar’s primary unique identifier for a paper.
example: 5c5751d45e298cea054f32b392c12c61027d2fe7
corpusId:
type: integer
description: Semantic Scholar’s secondary unique identifier for a paper.
example: 215416146
url:
type: string
description: URL of the paper on the Semantic Scholar website.
example: https://www.semanticscholar.org/paper/5c5751d45e298cea054f32b392c12c61027d2fe7
title:
type: string
description: Title of the paper.
example: Construction of the Literature Graph in Semantic Scholar
venue:
type: string
description: The name of the paper’s publication venue.
example: Annual Meeting of the Association for Computational Linguistics
publicationVenue:
type: object
description: 'An object that contains the following information about the journal or conference in which this paper was published: id (the venue’s unique ID), name (the venue’s name), type (the type of venue), alternate_names (an array of alternate names for the venue), and url (the venue’s website).'
example:
id: 1e33b3be-b2ab-46e9-96e8-d4eb4bad6e44
name: Annual Meeting of the Association for Computational Linguistics
type: conference
alternate_names:
- Annu Meet Assoc Comput Linguistics
- Meeting of the Association for Computational Linguistics
- ACL
- Meet Assoc Comput Linguistics
url: https://www.aclweb.org/anthology/venues/acl/
year:
type: integer
description: The year the paper was published.
example: 1997
authors:
type: array
title: Author Info
description: Details about the paper's authors
items:
$ref: '#/components/schemas/AuthorInfo'
type: object
BasePaper:
properties:
paperId:
type: string
description: Semantic Scholar’s primary unique identifier for a paper.
example: 5c5751d45e298cea054f32b392c12c61027d2fe7
corpusId:
type: integer
description: Semantic Scholar’s secondary unique identifier for a paper.
example: 215416146
externalIds:
type: object
description: 'An object that contains the paper’s unique identifiers in external sources. The external sources are limited to: ArXiv, MAG, ACL, PubMed, Medline, PubMedCentral, DBLP, and DOI.'
example:
MAG: '3015453090'
DBLP: conf/acl/LoWNKW20
ACL: 2020.acl-main.447
DOI: 10.18653/V1/2020.ACL-MAIN.447
CorpusId: 215416146
url:
type: string
description: URL of the paper on the Semantic Scholar website.
example: https://www.semanticscholar.org/paper/5c5751d45e298cea054f32b392c12c61027d2fe7
title:
type: string
description: Title of the paper.
example: Construction of the Literature Graph in Semantic Scholar
abstract:
type: string
description: The paper's abstract. Note that due to legal reasons, this may be missing even if we display an abstract on the website.
example: We describe a deployed scalable system for organizing published scientific literature into a heterogeneous graph to facilitate algorithmic manipulation and discovery.
venue:
type: string
description: The name of the paper’s publication venue.
example: Annual Meeting of the Association for Computational Linguistics
publicationVenue:
type: object
description: 'An object that contains the following information about the journal or conference in which this paper was published: id (the venue’s unique ID), name (the venue’s name), type (the type of venue), alternate_names (an array of alternate names for the venue), and url (the venue’s website).'
example:
id: 1e33b3be-b2ab-46e9-96e8-d4eb4bad6e44
name: Annual Meeting of the Association for Computational Linguistics
type: conference
alternate_names:
- Annu Meet Assoc Comput Linguistics
- Meeting of the Association for Computational Linguistics
- ACL
- Meet Assoc Comput Linguistics
url: https://www.aclweb.org/anthology/venues/acl/
year:
type: integer
description: The year the paper was published.
example: 1997
referenceCount:
type: integer
description: The total number of papers this paper references.
example: 59
citationCount:
type: integer
description: The total number of papers that references this paper.
example: 453
influentialCitationCount:
type: integer
description: 'A subset of the citation count, where the cited publication has a significant impact on the citing publication. Determined by Semantic Scholar’s algorithm: https://www.semanticscholar.org/faq#influential-citations.'
example: 90
isOpenAccess:
type: boolean
description: 'Whether the paper is open access. More information here: https://www.openaccess.nl/en/what-is-open-access.'
example: true
openAccessPdf:
type: object
description: 'An object that contains the following parameters: url (a link to the paper’s PDF), status (the type of open access https://en.wikipedia.org/wiki/Open_access#Colour_naming_system), the paper''s license, and a legal disclaimer.'
example:
url: https://www.aclweb.org/anthology/2020.acl-main.447.pdf
status: HYBRID
license: CCBY
disclaimer: 'Notice: This snippet is extracted from the open access paper or abstract available at https://aclanthology.org/2020.acl-main.447, which is subject to the license by the author or copyright owner provided with this content. Please go to the source to verify the license and copyright information for your use.'
fieldsOfStudy:
type: array
description: 'A list of the paper’s high-level academic categories from external sources. The possible fields are: Computer Science, Medicine, Chemistry, Biology, Materials Science, Physics, Geology, Psychology, Art, History, Geography, Sociology, Business, Political Science, Economics, Philosophy, Mathematics, Engineering, Environmental Science, Agricultural and Food Sciences, Education, Law, and Linguistics.'
example:
- Computer Science
items:
type: string
s2FieldsOfStudy:
type: array
description: 'An array of objects. Each object contains the following parameters: category (a field of study. The possible fields are the same as in fieldsOfStudy), and source (specifies whether the category was classified by Semantic Scholar or by an external source. More information on how Semantic Scholar classifies papers https://medium.com/ai2-blog/announcing-s2fos-an-open-source-academic-field-of-study-classifier-9d2f641949e5)'
example:
- category: Computer Science
source: external
- category: Computer Science
source: s2-fos-model
- category: Mathematics
source: s2-fos-model
items:
type: object
publicationTypes:
type: array
description: The type of this publication.
example:
- Journal Article
- Review
items:
type: string
publicationDate:
type: string
description: The date when this paper was published, in YYYY-MM-DD format.
example: '2024-04-29'
journal:
type: object
description: 'An object that contains the following parameters, if available: name (the journal name), volume (the journal’s volume number), and pages (the page number range)'
example:
volume: '40'
pages: 116 - 135
name: IETE Technical Review
citationStyles:
type: object
description: The BibTex bibliographical citation of the paper.
example:
bibtex: "@['JournalArticle', 'Conference']{Ammar2018ConstructionOT,\n author = {Waleed Ammar and Dirk Groeneveld and Chandra Bhagavatula and Iz Beltagy and Miles Crawford and Doug Downey and Jason Dunkelberger and Ahmed Elgohary and Sergey Feldman and Vu A. Ha and Rodney Michael Kinney and Sebastian Kohlmeier and Kyle Lo and Tyler C. Murray and Hsu-Han Ooi and Matthew E. Peters and Joanna L. Power and Sam Skjonsberg and Lucy Lu Wang and Christopher Wilhelm and Zheng Yuan and Madeleine van Zuylen and Oren Etzioni},\n booktitle = {NAACL},\n pages = {84-91},\n title = {Construction of the Literature Graph in Semantic Scholar},\n year = {2018}\n}\n"
authors:
type: array
title: Author Info
description: Details about the paper's authors
items:
$ref: '#/components/schemas/AuthorInfo'
type: object
AuthorSearchBatch:
properties:
total:
type: string
description: 'Approximate number of matching search results.
Because of the subtleties of finding partial phrase matches in different parts of the document, be cautious about interpreting the total field as a count of documents containing any particular word in the query.'
example: 15117
offset:
type: integer
description: Starting position for this batch.
next:
type: integer
description: Starting position of the next batch. Absent if no more data exists.
data:
type: array
items:
title: contents of this batch
allOf:
- $ref: '#/components/schemas/AuthorWithPapers'
type: object
AuthorWithPapers:
properties:
authorId:
type: string
title: This field will be provided if no fields are specified
description: Semantic Scholar’s unique ID for the author.
example: '1741101'
externalIds:
type: object
description: An object that contains the ORCID/DBLP IDs for the author, if known.
example:
DBLP:
- 123
url:
type: string
description: URL of the author on the Semantic Scholar website.
example: https://www.semanticscholar.org/author/1741101
name:
type: string
title: This field will be provided if no fields are specified
description: Author’s name.
example: Oren Etzioni
affiliations:
type: array
description: Array of organizational affiliations for the author.
example:
- Allen Institute for AI
items:
type: string
homepage:
type: string
description: The author’s homepage.
example: https://allenai.org/
paperCount:
type: string
description: The author's total publications count.
example: 10
citationCount:
type: string
description: The author's total citations count.
example: 50
hIndex:
type: string
description: 'The author’s h-index, which is a measure of the productivity and citation impact of the author’s publications: https://www.semanticscholar.org/faq#h-index'
example: 5
papers:
type: array
items:
title: Paper Info
allOf:
- $ref: '#/components/schemas/BasePaper'
type: object
PaperWithLinks:
properties:
paperId:
type: string
description: Semantic Scholar’s primary unique identifier for a paper.
example: 5c5751d45e298cea054f32b392c12c61027d2fe7
corpusId:
type: integer
description: Semantic Scholar’s secondary unique identifier for a paper.
example: 215416146
externalIds:
type: object
description: 'An object that contains the paper’s unique identifiers in external sources. The external sources are limited to: ArXiv, MAG, ACL, PubMed, Medline, PubMedCentral, DBLP, and DOI.'
example:
MAG: '3015453090'
DBLP: conf/acl/LoWNKW20
ACL: 2020.acl-main.447
DOI: 10.18653/V1/2020.ACL-MAIN.447
CorpusId: 215416146
url:
type: string
description: URL of the paper on the Semantic Scholar website.
example: https://www.semanticscholar.org/paper/5c5751d45e298cea054f32b392c12c61027d2fe7
title:
type: string
description: Title of the paper.
example: Construction of the Literature Graph in Semantic Scholar
abstract:
type: string
description: The paper's abstract. Note that due to legal reasons, this may be missing even if we display an abstract on the website.
example: We describe a deployed scalable system for organizing published scientific literature into a heterogeneous graph to facilitate algorithmic manipulation and discovery.
venue:
type: string
description: The name of the paper’s publication venue.
example: Annual Meeting of the Association for Computational Linguistics
publicationVenue:
type: object
description: 'An object that contains the following information about the journal or conference in which this paper was published: id (the venue’s unique ID), name (the venue’s name), type (the type of venue), alternate_names (an array of alternate names for the venue), and url (the venue’s website).'
example:
id: 1e33b3be-b2ab-46e9-96e8-d4eb4bad6e44
name: Annual Meeting of the Association for Computational Linguistics
type: conference
alternate_names:
- Annu Meet Assoc Comput Linguistics
- Meeting of the Association for Computational Linguistics
- ACL
- Meet Assoc Comput Linguistics
url: https://www.aclweb.org/anthology/venues/acl/
year:
type: integer
description: The year the paper was published.
example: 1997
referenceCount:
type: integer
description: The total number of papers this paper references.
example: 59
citationCount:
type: integer
description: The total number of papers that references this paper.
example: 453
influentialCitationCount:
type: integer
description: 'A subset of the citation count, where the cited publication has a significant impact on the citing publication. Determined by Semantic Scholar’s algorithm: https://www.semanticscholar.org/faq#influential-citations.'
example: 90
isOpenAccess:
type: boolean
description: 'Whether the paper is open access. More information here: https://www.openaccess.nl/en/what-is-open-access.'
example: true
openAccessPdf:
type: object
description: 'An object that contains the following parameters: url (a link to the paper’s PDF), status (the type of open access https://en.wikipedia.org/wiki/Open_access#Colour_naming_system), the paper''s license, and a legal disclaimer.'
example:
url: https://www.aclweb.org/anthology/2020.acl-main.447.pdf
status: HYBRID
license: CCBY
disclaimer: 'Notice: This snippet is extracted from the open access paper or abstract available at https://aclanthology.org/2020.acl-main.447, which is subject to the license by the author or copyright owner provided with this content. Please go to the source to verify the license and copyright information for your use.'
fieldsOfStudy:
type: array
description: 'A list of the paper’s high-level academic categories from external sources. The possible fields are: Computer Science, Medicine, Chemistry, Biology, Materials Science, Physics, Geology, Psychology, Art, History, Geography, Sociology, Business, Political Science, Economics, Philosophy, Mathematics, Engineering, Environmental Science, Agricultural and Food Sciences, Education, Law, and Linguistics.'
example:
- Computer Science
items:
type: string
s2FieldsOfStudy:
type: array
description: 'An array of objects. Each object contains the following parameters: category (a field of study. The possible fields are the same as in fieldsOfStudy), and source (specifies whether the category was classified by Semantic Scholar or by an external source. More information on how Semantic Scholar classifies papers https://medium.com/ai2-blog/announcing-s2fos-an-open-source-academic-field-of-study-classifier-9d2f641949e5)'
example:
- category: Computer Science
source: external
- category: Computer Science
source: s2-fos-model
- category: Mathematics
source: s2-fos-model
items:
type: object
publicationTypes:
type: array
description: The type of this publication.
example:
- Journal Article
- Review
items:
type: string
publicationDate:
type: string
description: The date when this paper was published, in YYYY-MM-DD format.
example: '2024-04-29'
journal:
type: object
description: 'An object that contains the following parameters, if available: name (the journal name), volume (the journal’s volume number), and pages (the page number range)'
example:
volume: '40'
pages: 116 - 135
name: IETE Technical Review
citationStyles:
type: object
description: The BibTex bibliographical citation of the paper.
example:
bibtex: "@['JournalArticle', 'Conference']{Ammar2018ConstructionOT,\n author = {Waleed Ammar and Dirk Groeneveld and Chandra Bhagavatula and Iz Beltagy and Miles Crawford and Doug Downey and Jason Dunkelberger and Ahmed Elgohary and Sergey Feldman and Vu A. Ha and Rodney Michael Kinney and Sebastian Kohlmeier and Kyle Lo and Tyler C. Murray and Hsu-Han Ooi and Matthew E. Peters and Joanna L. Power and Sam Skjonsberg and Lucy Lu Wang and Christopher Wilhelm and Zheng Yuan and Madeleine van Zuylen and Oren Etzioni},\n booktitle = {NAACL},\n pages = {84-91},\n title = {Construction of the Literature Graph in Semantic Scholar},\n year = {2018}\n}\n"
authors:
type: array
title: Author Info
description: Details about the paper's authors
items:
$ref: '#/components/schemas/AuthorInfo'
citations:
type: array
title: Paper Info
items:
$ref: '#/components/schemas/PaperInfo'
references:
type: array
items:
title: Paper Info
allOf:
- $ref: '#/components/schemas/PaperInfo'
type: object
Error404:
properties:
error:
type: string
description: "Depending on the case, error message may be any of these:\n<ul>\n <li><code>\"Paper/Author/Object not found\"</code></li>\n <li><code>\"Paper/Author/Object with id ### not found\"</code></li>\n</ul>"
example: Requested object not found
type: object
AuthorInfo:
properties:
authorId:
type: string
title: This field will be provided if no fields are specified
description: Semantic Scholar’s unique ID for the author.
example: '1741101'
name:
type: string
title: This field will be provided if no fields are specified
description: Author’s name.
example: Oren Etzioni
type: object