CINXE.COM
CORE API Documentation
<!DOCTYPE html> <html lang="en"> <head> <title>CORE API Documentation</title> <meta charset="utf-8"/> <meta name="viewport" content="width=device-width, initial-scale=1"> <style> body { margin: 0; padding: 0; } blockquote { color: rgba(0, 0, 0, .87) !important; border-left: 3px solid #b75400 !important; background-color: #f5f5f5 !important; padding: .5rem .5rem !important; } .linkDocs { background-color: rgba(190, 100, 22, 0.12); padding: 5px 10px; border-radius: 3px; } .preCode { background: #f6f8fa !important; border-radius: 6px !important; overflow-x: auto !important; padding: 20px !important; } .codePython { color: #333 !important; font-family: monospace !important; font-size: 0.9em !important; border: none !important; white-space: pre !important; } [data-item-id="tag/Entities"] span[type="options"].operation-type.options { opacity: 0; } [data-item-id="tag/Rate-limits"] span[type="options"].operation-type.options { opacity: 0; } [data-item-id="tag/Search/operation/optionsCustomSearchWorks"] span[type="options"].operation-type.options { opacity: 0; } [data-item-id="tag/Search/operation/optionsCustomSearchOutputs"] span[type="options"].operation-type.options { opacity: 0; } [data-item-id="tag/Search/operation/optionsCustomSearchDataProviders"] span[type="options"].operation-type.options { opacity: 0; } [data-item-id="tag/Search/operation/optionsCustomSearchJournals"] span[type="options"].operation-type.options { opacity: 0; } [data-item-id="tag/Search/operation/optionsCustomQueryLanguage"] span[type="options"].operation-type.options { opacity: 0; } [data-item-id="tag/Search/operation/optionsCustomSearchAggregation"] span[type="options"].operation-type.options { opacity: 0; } /* Hide the auth section on left side */ [data-section-id="operation/optionsCustomDataProviders"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomJournals"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomWorks"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomOutputs"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearch"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomRecommender"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomDiscovery"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomRateLimitCommon"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomRateLimitMonitor"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchWorks"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchOutputs"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchDataProviders"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchJournals"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomQueryLanguage"] > div:first-child > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchAggregation"] > div:first-child > div:last-child { opacity: 0; } /* Hide the path section on right side */ [data-section-id="operation/optionsCustomDataProviders"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomJournals"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomWorks"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomOutputs"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearch"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomRecommender"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomDiscovery"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomRateLimitCommon"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomRateLimitMonitor"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchWorks"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchOutputs"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchDataProviders"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchJournals"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomQueryLanguage"] > div:last-child { opacity: 0; } [data-section-id="operation/optionsCustomSearchAggregation"] > div:last-child { opacity: 0; } </style> </head> <body> <div id="redoc-container"></div> <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script> <script> // System typefaces extracted from sanitize.css // More: https://github.com/csstools/sanitize.css/blob/master/typography.css const fontFamilySans = '"Roboto", system-ui, -apple-system, "Segoe UI", "Ubuntu", "Cantarell", "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"'; const fontFamilyMono = '"Fira Code", "Menlo", "Consolas", "Roboto Mono", "Ubuntu Monospace", "Noto Mono", "Oxygen Mono", "Liberation Mono", monospace, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"'; const theme = { colors: { primary: { main: '#b75400', }, success: { main: '#5a9216', }, warning: { main: '#f9bc04', contrastText: 'rgba(0, 0, 0, .87)', }, error: { main: '#c62828', }, gray: { 50: '#fafafa', 100: '#f5f5f5', }, text: { primary: 'rgba(0, 0, 0, .87)', secondary: 'rgba(0, 0, 0, .6)', }, border: { dark: 'rgba(0, 0, 0, .12)', }, responses: { info: { color: '#01749e', }, }, http: { get: '#5a9216', post: '#01749e', }, }, typography: { fontFamily: fontFamilySans, fontSize: '1rem', lineHeight: '1.5', headings: { fontFamily: fontFamilySans, fontWeight: 600, lineHeight: '1.25', }, code: { fontFamily: fontFamilyMono, fontSize: '0.85rem', }, }, sidebar: { width: '16rem', backgroundColor: '#f5f5f5', textColor: 'rgba(0, 0, 0, .87)', activeTextColor: ({colors}) => colors.primary.main, }, logo: { gutter: '1rem', }, rightPanel: { backgroundColor: '#424242', }, codeBlock: { backgroundColor: '#212121', }, }; const options = { theme, hideDownloadButton: true, nativeScrollbars: true, unsafeMarkdown: true }; const mountElement = document.getElementById('redoc-container'); const logo = { url: 'https://oacore.github.io/content/images/logos/core-api.svg', altText: 'CORE API', } const specUrl = '/swagger/v3.json'; fetch(specUrl) .then((response) => response.json()) .then((spec) => { spec.info['x-logo'] = logo; spec.paths["/custom/entities/data_providers"] = { options: { summary: "Data Providers", description: "It gives you access to the collection of entities that offer data to CORE. " + "It contains repositories (institutional and disciplinary), preprint servers, journals and publishers.", operationId: "optionsCustomDataProviders", tags: ["Entities"], }, }; spec.paths["/custom/entities/journals"] = { options: { summary: "Journals", description: "This dataset contains all journal titles included in the CORE collection. " + "Moreover, you can search and retrieve any journal even if it is not a CORE data provider.", operationId: "optionsCustomJournals", tags: ["Entities"], }, }; spec.paths["/custom/entities/Works"] = { options: { summary: "Works", description: "These are the entities that represent a piece of research, .e.g research articles, theses, etc." + "In total, it is a deduplicated and enriched version of records.", operationId: "optionsCustomWorks", tags: ["Entities"], }, }; spec.paths["/custom/entities/Outputs"] = { options: { summary: "Outputs", description: "Outputs are a representation of a <b>Work</b> in a data provider." + "The data is not enriched and it mirrors exactly the content harvested from the data provider.", operationId: "optionsCustomOutputs", tags: ["Entities"], }, }; const searchWorksPath = { options: { summary: "Search by Works", description: "Search within the CORE works entity using specific query parameters and fields. Below are detailed instructions and examples of how to perform targeted searches.<br/><br/>" + "Example Searches<br/><br/>" + "<b>Search works by DOI:</b><br/>" + "Retrieve works with a specific DOI:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/works?q=doi:\"10.1038/s41597-023-02208-w\"</span><br/><br/>" + "<b>Search works by Title:</b><br/>" + "Retrieve works with a specific title, limiting the results to 1:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/works?q=title:\"Mathematics\"&limit=1</span><br/><br/>" + "<b>Search works by keywords in full-text:</b><br/>" + "Retrieve works containing \"sustainable development goals\" in the fulltext, with pagination set to 5:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/works?q=fullText:\"development\"&offset=5</span><br/><br/>" + "<b>Search works by author name:</b><br/>" + "Retrieve works authored by a specific individual:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/works?q=authors:\"Jane\"</span><br/><br/>" + "Example python source code to search works by DOI:<br/>" + "<pre class='preCode'>" + "<code class='codePython'>" + " def search_works_by_doi(doi:str):<br/>" + " url = \\\"https://api.core.ac.uk/v3/search/works\\\"<br/>" + " headers = {\\\"Authorization\\\": f\\\"Bearer {apikey}\\\"}<br/>" + " params = {\\\"q\\\": f\\\"doi:\\\"{doi}\\\"\\\", \\\"limit\\\": 1}<br/>" + " try:<br/>" + " response = requests.get(url, headers=headers, params=params)<br/>" + " if response.status_code == 200:<br/>" + " return response.json()<br/>" + " else:<br/>" + " print(f\\\"Error {response.status_code}: {response.text}\\\")<br/>" + " return None<br/>" + " except requests.exceptions.RequestException as e:<br/>" + " print(f\\\"Request failed: {e}\\\")<br/>" + " return None" + "</code>" + "</pre>", operationId: "optionsCustomSearchWorks", tags: ["Search"], }, }; const searchOutputsPath = { options: { summary: "Search by Outputs", description: "Search through the CORE outputs entity using specific query parameters and fields. " + "Below are detailed instructions and examples of how to perform targeted searches.<br/><br/>" + "Example Searches<br/><br/>" + "<b>Search outputs by id:</b><br/>" + "Retrieve outputs with a specific CORE ID:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/outputs?q=id:\\\"571215426\\\"</span><br/><br/>" + "<b>Search outputs by Title:</b><br/>" + "Retrieve outputs with a specific title, limiting the results to 1:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/outputs?q=title:\\\"Mathematics\\\"&limit=1</span><br/><br/>" + "<b>Search outputs by keywords in full-text:</b><br/>" + "Retrieve outputs containing \\\"sustainable development goals\\\" in the full-text, with pagination offset set to 5:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/outputs?q=fullText:\\\"development\\\"&offset=5</span><br/><br/>" + "<b>Search outputs by author name:</b><br/>" + "Retrieve outputs authored by a specific individual:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/outputs?q=authors:\\\"Jane\\\"</span><br/><br/>" + "Example source code to search outputs by keywords in full-text:<br/>" + "<pre class='preCode'>" + "<code class='codePython'>" + " def search_outputs_by_keywords(keywords:str):<br/>" + " url = \\\"https://api.core.ac.uk/v3/search/outputs\\\"<br/>" + " headers = {\\\"Authorization\\\": f\\\"Bearer {apikey}\\\"}<br/>" + " params = {\\\"q\\\": f\\\"fullText:\\\"{keywords}\\\"\\\", \\\"limit\\\": 5}<br/>" + " try:<br/>" + " response = requests.get(url, headers=headers, params=params)<br/>" + " if response.status_code == 200:<br/>" + " return response.json()<br/>" + " else:<br/>" + " print(f\\\"Error {response.status_code}: {response.text}\\\")<br/>" + " return None<br/>" + " except requests.exceptions.RequestException as e:<br/>" + " print(f\\\"Request failed: {e}\\\")<br/>" + " return None" + "</code>" + "</pre>" , operationId: "optionsCustomSearchOutputs", tags: ["Search"], }, }; const searchDataProvidersPath = { options: { summary: "Search by Data providers", description: "Search through the CORE data-providers entity using specific query parameters and fields. " + "Below are detailed instructions and examples of how to perform targeted searches.<br/><br/>" + "Example Searches<br/>" + "<b>Search data providers by ID:</b><br/>" + "Retrieve data providers with a specific id:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/data-providers?q=id:\\\"86\\\"</span><br/><br/>" + "<b>Search data providers by Name:</b><br/>" + "Retrieve data providers based on the name:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/data-providers?q=name:\\\"NERC\\\"</span><br/><br/>" + "<b>Search data providers by Institution Name:</b><br/>" + "Retrieve data providers from a specific institution:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/data-providers?q=institutionName:\\\"Glasgow\\\"</span><br/><br/>" + "Example source code to search data-providers by ID:" + "<pre class='preCode'>" + "<code class='codePython'>" + " def search_dp_by_id(id:str):<br>" + " url = \\\"https://api.core.ac.uk/v3/search/data-providers\\\"<br>" + " headers = {\\\"Authorization\\\": f\\\"Bearer {apikey}\\\"}<br>" + " params = {\\\"q\\\": f\\\"id:\\\"{id}\\\"\\\", \\\"limit\\\": 1}<br>" + " try:<br>" + " response = requests.get(url, headers=headers, params=params)<br>" + " if response.status_code == 200:<br>" + " return response.json()<br>" + " else:<br>" + " print(f\\\"Error {response.status_code}: {response.text}\\\")<br>" + " return None<br>" + " except requests.exceptions.RequestException as e:<br>" + " print(f\\\"Request failed: {e}\\\")<br>" + " return None" + "</code>" + "</pre>", operationId: "optionsCustomSearchDataProviders", tags: ["Search"], }, }; const searchJournalsPath = { options: { summary: "Search by Journals", description: "Search through the CORE journals entity using specific query parameters. Below are detailed instructions and examples of targeted searches.<br/><br/>" + "Example Searches<br/>" + "<b>Search journals by Identifier (ISSN):</b><br/>" + "Retrieve journals with a specific ISSN:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/journals?q=\\\"1744-9081\\\"</span><br/><br/>" + "<b>Search journals by Name:</b><br/>" + "Retrieve journals with a specific title:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/journals/?q=title:\\\"BioData\\\"</span><br/><br/>" + "<b>Search journals by subject:</b><br/>" + "Retrieve journals based on the input subject, limiting to 5 records and pagination set to 1:<br/>" + "<span class='linkDocs'>https://api.core.ac.uk/v3/search/journals?q=subject:\\\"Computing\\\"&limit=5&offset=1</span><br/><br/><br/>" + "Example source code to search journals by subject:<br/>" + "<pre class='preCode'>" + "<code class='codePython'>" + " def search_journal_by_subject(subject:str):<br>" + " url = \\\"https://api.core.ac.uk/v3/search/journals\\\"<br>" + " headers = {\\\"Authorization\\\": f\\\"Bearer {apikey}\\\"}<br>" + " params = {\\\"q\\\": f\\\"subjects:\\\"{subject}\\\"\\\", \\\"limit\\\": 1, \\\"offset\\\":1}<br>" + " try:<br>" + " response = requests.get(url, headers=headers, params=params)<br>" + " if response.status_code == 200:<br>" + " return response.json()<br>" + " else:<br>" + " print(f\\\"Error {response.status_code}: {response.text}\\\")<br>" + " return None<br>" + " except requests.exceptions.RequestException as e:<br>" + " print(f\\\"Request failed: {e}\\\")<br>" + " return None" + "</code>" + "</pre>", operationId: "optionsCustomSearchJournals", tags: ["Search"], }, }; const searchQueryLanguagePath = { options: { summary: "CORE API Query Language", description: "The CORE API query language allows users to explore the CORE collection " + "and construct complex queries using various operators. " + "The following table outlines the available operators and their usage: <br/>" + "<table>" + "<tr>" + " <td>Operator</td>" + " <td>Accepted symbols</td>" + " <td>Meaning</td>" + "</tr>" + "<tr>" + " <td>And</td>" + " <td><code>AND</code>, <code>+</code>, <code>space</code></td>" + " <td>Logical binary AND. Used to retrieve results matching all conditions.</td>" + "</tr>" + "<tr>" + " <td>Or</td>" + " <td><code>OR</code></td>" + " <td>Logical binary OR. Used to retrieve results matching at least one condition.</td>" + "</tr>" + "<tr>" + " <td>Grouping</td>" + " <td><code>(...)</code></td>" + " <td>Used to prioritize and group elements of the query.</td>" + "</tr>" + "<tr>" + " <td>Field lookup</td>" + " <td><code>field_name:value</code></td>" + " <td>Used to search specific fields (e.g., <code>title:\\\"Artificial Intelligence\\\"</code>).</td>" + "</tr>" + "<tr>" + " <td>Range queries</td>" + " <td><code>fieldName(>, <, >=, <=) value</code></td>" + " <td>For numeric and date fields, specifies a range of values.</td>" + "</tr>" + "<tr>" + " <td>Exists queries</td>" + " <td><code>_exists_:fieldName</code></td>" + " <td>Returns all items where the specified field is not empty.</td>" + "</tr>" + "</table>" + "<h3>Examples of Query Usage</h3>" + "1. <b>Field lookup</b>: Search for works with \\\"Machine Learning\\\" in the title" + "<pre class='preCode'>" + "<code class='codePython'>" + "q=title:\\\"<b>Machine Learning</b>\\\"" + "</code>" + "</pre>" + "<br/>" + "2. <b>Range queries:</b> Search for works published after 2018" + "<pre class='preCode'>" + "<code class='codePython'>" + "q=yearPublished><b>2018</b>" + "</code>" + "</pre>" + "<br/>" + "3. <b>AND:</b> Search for works by multiple authors" + "<pre class='preCode'>" + "<code class='codePython'>" + "q=authors:\\\"<b>Jane Doe</b>\\\" AND authors:\\\"<b>John Smith</b>\\\"" + "</code>" + "</pre>" + "<br/>" + "4. <b>OR:</b> Search works with \\\"AI\\\" in the title or \\\"Deep Learning\\\" in the full-text" + "<pre class='preCode'>" + "<code class='codePython'>" + "q=title:\\\"<b>AI</b>\\\" OR fullText:\\\"<b>Deep Learning</b>\\\"" + "</code>" + "</pre>" + "<br/>" + "5. <b>Exists queries:</b> Find works with full-text available" + "<pre class='preCode'>" + "<code class='codePython'>" + "q=_exists_:fullText" + "</code>" + "</pre>" + "<br/>" + "6. <b>Grouping:</b> Search works using multiple conditions" + "<pre class='preCode'>" + "<code class='codePython'>" + "q=(title:\\\"<b>Artificial Intelligence</b>\\\" OR title:\\\"<b>Machine Learning</b>\\\") AND yearPublished>\\\"<b>2020</b>\\\"" + "</code>" + "</pre>" , operationId: "optionsCustomQueryLanguage", tags: ["Search"], }, }; const searchSearchAggregationPath = { options: { summary: "Aggregation Request", description: "POST request body example:<br/>" + "<pre class='preCode'>" + "<code class='codePython'>" + "{<br/> \\\"q\\\": \\\"climate change\\\", \\\"aggregations\\\": [\\\"yearPublished\\\", \\\"authors\\\"]<br/>}" + "</code>" + "</pre>" + "Example source code to aggregate results for works based on the above request body:<br/>" + "<pre class='preCode'>" + "<code class='codePython'>" + "def search_with_aggregation(query):<br/>" + " url = \\\"https://api.core.ac.uk/v3/search/works/aggregate\\\"<br/>" + " headers = {<br/>" + " \\\"Authorization\\\": f\\\"Bearer {apikey}\\\",<br/>" + " \\\"Content-Type\\\": \\\"application/json\\\"<br/>" + " }<br/>" + " data = {<br/>" + " \\\"q\\\": query,<br/>" + " \\\"aggregations\\\": [\\\"yearPublished\\\", \\\"authors\\\"]<br/>" + " }<br/>" + " try:<br/>" + " response = requests.post(url, json=data, headers=headers)<br/>" + " if response.status_code == 200:<br/>" + " print(\\\"Aggregation Results:\\\")<br/>" + " print(response.json())<br/>" + " else:<br/>" + " print(f\\\"Error {response.status_code}: {response.text}\\\")<br/>" + " except requests.exceptions.RequestException as e:<br/>" + " print(f\\\"Request failed: {e}\\\")" + "</code>" + "</pre>" + "Aggregation response sample for <code>query=\\\"climate change\\\"</code><br/>" + "<pre class='preCode'>" + "<code class='codePython'>" + "{<br/>" + "\\\"aggregations\\\": {<br/>" + " \\\"yearPublished\\\": {<br/>" + " \\\"2025\\\": 4116,<br/>" + " \\\"2024\\\": 108312,<br/>" + " \\\"2023\\\": 151061,<br/>" + " \\\"2022\\\": 151742,<br/>" + " \\\"2021\\\": 135433,<br/>" + " \\\"2020\\\": 132744,<br/>" + " .....................<br/>" + " .....................<br/>" + " \\\"1897\\\": 605,<br/>" + " \\\"1896\\\": 664,<br/>" + " \\\"1892\\\": 543<br/>" + " },<br/>" + " \\\"authors\\\": {<br/>" + " \\\"Wang\\\": 5319,<br/>" + " \\\"Smith\\\": 4805,<br/>" + " \\\"Zhang\\\": 4524,<br/>" + " \\\"IPCC\\\": 4397,<br/>" + " ......................<br/>" + " ......................<br/>" + " \\\"Campbell\\\": 1101,<br/>" + " \\\"Hu\\\": 1101,<br/>" + " \\\"Wood\\\": 1100<br/>" + " }<br/>" + "}<br/>" + "}" + "</code>" + "</pre><br/>" + "<b>Note:</b> The aggregation feature does not support all fields returned by the API entity responses. " + "Only certain fields can be used effectively. For instance, you can aggregate works using the following fields: " + "<pre class='preCode'>" + "<code class='codePython'>" + "\\\"yearPublished\\\"<br/>" + "\\\"authors\\\"<br/>" + "\\\"dataProvider\\\"<br/>" + "\\\"documentType\\\"<br/>" + "\\\"publishedDate\\\"<br/>" + "\\\"updatedDate\\\"<br/>" + "\\\"language\\\"<br/>" + "\\\"publisher\\\"<br/>" + "\\\"fieldOfStudy\\\"<br/>" + "</code>" + "</pre><br/>" + "Outputs can be aggregated using the following fields:" + "<pre class='preCode'>" + "<code class='codePython'>" + "\\\"acceptedDate\\\"<br/>" + "\\\"authors\\\"<br/>" + "\\\"contributors\\\"<br/>" + "\\\"depositedDate\\\"<br/>" + "\\\"documentType\\\"<br/>" + "\\\"language\\\"<br/>" + "\\\"publishedDate\\\"<br/>" + "\\\"subjects\\\"<br/>" + "</code>" + "</pre><br/>" + "Data-providers entity supports following aggregations:" + "<pre class='preCode'>" + "<code class='codePython'>" + "\\\"software\\\"" + "</code>" + "</pre><br/>" + "Following fields from Journals entity supports aggregation:" + "<pre class='preCode'>" + "<code class='codePython'>" + "\\\"subjects\\\"" + "</code>" + "</pre>" , operationId: "optionsCustomSearchAggregation", tags: ["Search"], }, }; spec.paths["/v3/search/search-aggregation"] = searchSearchAggregationPath; spec.paths["/custom/rate_limit/common"] = { options: { summary: "Common", description: "Access to the CORE API is free and requires no authentication. Providing free access to general users is part of our mission. " + "Being a sustainable scholarly infrastructure is also part of our mission. As a result, we offer better performance to registered users. " + "The below table provides information about our rate limits depending on your situation.<br><br>" + "To control the load on our systems we use a rate-limiting technology based on tokens. Each user has access to a certain number of tokens " + "at the start of their session and they can use them to perform their queries.<br><br>" + "Certain calls in CORE are more computationally expensive than others, therefore some calls such as recommender, " + "scroll search and bulk queries will cost you more tokens than others. As a rule of thumb, a simple query will cost you 1 token " + "while more complex queries will cost you between 3 to 5 tokens. <br><br>" + "We are monitoring the load on our servers and at some point we might decide to increase or decrease the “cost” of certain " + "operations to control the overall load. The best way to keep on top of your API usage is to use the HTTP headers included " + "in every API call response (see below for details about the headers).<br><br>" + "<div><table><tbody><tr><td>User type</td><td>How to obtain</td><td>Rate limit</td><td>Support</td></tr>" + "<tr><td>Unauthenticated users</td><td>No registration required, just start using the API.</td>" + "<td>1,000 tokens per day, maximum 10 per minute. </td><td>No support</td></tr>" + "<tr><td>Registered Personal users</td><td> </td>" + "<td>10,000 tokens per day, maximum 10 per minute. </td><td>Best effort</td></tr>" + "<tr><td>Registered Academic (Supporting / Sustaining members) and Non-academic users</td><td> </td>" + "<td>The API limits are designed to allow reasonable usage and we will change them depending on the load on our servers. " + "However, on average, we estimate this plan should be good for up to about 200k tokens per day. You are able to monitor your current API limit " + "by looking for our customised HTTP headers: X-RateLimitRemaining X-RateLimit-Retry-After X-RateLimit-Limit</td>" + "<td>Dedicated support</td></tr>" + "<tr><td>VIP</td><td>Contact us to discuss a dedicated plan to upgrade your registration. </td>" + "<td>Sky is the limit. We can support your needs. Just let us know and we will find a way to accommodate your usage needs. </td>" + "<td>Unlimited priority support</td></tr>" + "</tbody></table></div>", operationId: "optionsCustomRateLimitCommon", tags: ["Rate limits"] } }; spec.paths["/custom/rate_limit/monitor"] = { options: { summary: "How to monitor your API rate limits", description: "The API limits are designed to allow reasonable usage and we will change them depending on the load on our servers." + "You are able to monitor our current api limit by looking for our customised HTTP headers:<br>" + "`X-RateLimitRemaining`<br>" + "`X-RateLimit-Retry-After`<br>" + "`X-RateLimit-Limit`<br>", operationId: "optionsCustomRateLimitMonitor", tags: ["Rate limits"] } }; const customPaths = {}; for (const path in spec.paths) { if (path.startsWith('/custom/entities/')) { customPaths[path] = spec.paths[path]; } } for (const path in customPaths) { delete spec.paths[path]; } const newPaths = {}; for (const path in spec.paths) { if (path === "/v3/search/{entityType}") { newPaths["/v3/search/works"] = searchWorksPath; } if (path === "/v3/search/{entityType}") { newPaths["/v3/search/outputs"] = searchOutputsPath; } if (path === "/v3/search/{entityType}") { newPaths["/v3/search/data-providers"] = searchDataProvidersPath; } if (path === "/v3/search/{entityType}") { newPaths["/v3/search/journals"] = searchJournalsPath; } if (path === "/v3/search/{entityType}") { newPaths["/v3/search/query-language"] = searchQueryLanguagePath; } // if (path === "/v3/search/{entityType}/aggregate") { // // if (path === "/v3/data-providers/{identifier}/stats") { // newPaths["/v3/search/search-aggregation"] = searchSearchAggregationPath; // } if (path === "/v3/data-providers/{identifier}") { for (const customPath in customPaths) { newPaths[customPath] = customPaths[customPath]; } } newPaths[path] = spec.paths[path]; } spec.paths = newPaths; console.log(spec); //dev Redoc.init(spec, options, mountElement); }); </script> </body> </html>