# Table of Contents - [Overview | OpenAlex technical documentation](#overview-openalex-technical-documentation) - [API Guide for LLMs | OpenAlex technical documentation](#api-guide-for-llms-openalex-technical-documentation) - [Quickstart tutorial | OpenAlex technical documentation](#quickstart-tutorial-openalex-technical-documentation) - [Works | OpenAlex technical documentation](#works-openalex-technical-documentation) - [Entities overview | OpenAlex technical documentation](#entities-overview-openalex-technical-documentation) - [Get N-grams | OpenAlex technical documentation](#get-n-grams-openalex-technical-documentation) - [Authors | OpenAlex technical documentation](#authors-openalex-technical-documentation) - [Get a single work | OpenAlex technical documentation](#get-a-single-work-openalex-technical-documentation) - [Authorship object | OpenAlex technical documentation](#authorship-object-openalex-technical-documentation) - [Location object | OpenAlex technical documentation](#location-object-openalex-technical-documentation) - [Search works | OpenAlex technical documentation](#search-works-openalex-technical-documentation) - [Author disambiguation | OpenAlex technical documentation](#author-disambiguation-openalex-technical-documentation) - [Sources | OpenAlex technical documentation](#sources-openalex-technical-documentation) - [Limitations | OpenAlex technical documentation](#limitations-openalex-technical-documentation) - [Get lists of works | OpenAlex technical documentation](#get-lists-of-works-openalex-technical-documentation) - [Group authors | OpenAlex technical documentation](#group-authors-openalex-technical-documentation) - [Get a single author | OpenAlex technical documentation](#get-a-single-author-openalex-technical-documentation) - [Group works | OpenAlex technical documentation](#group-works-openalex-technical-documentation) - [Filter sources | OpenAlex technical documentation](#filter-sources-openalex-technical-documentation) - [Group sources | OpenAlex technical documentation](#group-sources-openalex-technical-documentation) - [Topics | OpenAlex technical documentation](#topics-openalex-technical-documentation) - [Institutions | OpenAlex technical documentation](#institutions-openalex-technical-documentation) - [Get lists of sources | OpenAlex technical documentation](#get-lists-of-sources-openalex-technical-documentation) - [Search sources | OpenAlex technical documentation](#search-sources-openalex-technical-documentation) - [Topic object | OpenAlex technical documentation](#topic-object-openalex-technical-documentation) - [Publishers | OpenAlex technical documentation](#publishers-openalex-technical-documentation) - [Filter authors | OpenAlex technical documentation](#filter-authors-openalex-technical-documentation) - [Get a single source | OpenAlex technical documentation](#get-a-single-source-openalex-technical-documentation) - [Filter institutions | OpenAlex technical documentation](#filter-institutions-openalex-technical-documentation) - [Get lists of authors | OpenAlex technical documentation](#get-lists-of-authors-openalex-technical-documentation) - [Search institutions | OpenAlex technical documentation](#search-institutions-openalex-technical-documentation) - [Get a single award | OpenAlex technical documentation](#get-a-single-award-openalex-technical-documentation) - [Get a single publisher | OpenAlex technical documentation](#get-a-single-publisher-openalex-technical-documentation) - [Search authors | OpenAlex technical documentation](#search-authors-openalex-technical-documentation) - [Keywords | OpenAlex technical documentation](#keywords-openalex-technical-documentation) - [Geo | OpenAlex technical documentation](#geo-openalex-technical-documentation) - [Funders | OpenAlex technical documentation](#funders-openalex-technical-documentation) - [Get a single topic | OpenAlex technical documentation](#get-a-single-topic-openalex-technical-documentation) - [Group topics | OpenAlex technical documentation](#group-topics-openalex-technical-documentation) - [Get a single institution | OpenAlex technical documentation](#get-a-single-institution-openalex-technical-documentation) - [Filter topics | OpenAlex technical documentation](#filter-topics-openalex-technical-documentation) - [Group publishers | OpenAlex technical documentation](#group-publishers-openalex-technical-documentation) - [Get lists of publishers | OpenAlex technical documentation](#get-lists-of-publishers-openalex-technical-documentation) - [Group institutions | OpenAlex technical documentation](#group-institutions-openalex-technical-documentation) - [Group funders | OpenAlex technical documentation](#group-funders-openalex-technical-documentation) - [Search topics | OpenAlex technical documentation](#search-topics-openalex-technical-documentation) - [Get lists of topics | OpenAlex technical documentation](#get-lists-of-topics-openalex-technical-documentation) - [Continents | OpenAlex technical documentation](#continents-openalex-technical-documentation) - [Regions | OpenAlex technical documentation](#regions-openalex-technical-documentation) - [Filter publishers | OpenAlex technical documentation](#filter-publishers-openalex-technical-documentation) - [Awards | OpenAlex technical documentation](#awards-openalex-technical-documentation) - [Aboutness endpoint (/text) | OpenAlex technical documentation](#aboutness-endpoint-text-openalex-technical-documentation) - [Select fields | OpenAlex technical documentation](#select-fields-openalex-technical-documentation) - [Search publishers | OpenAlex technical documentation](#search-publishers-openalex-technical-documentation) - [Get a single funder | OpenAlex technical documentation](#get-a-single-funder-openalex-technical-documentation) - [Author object | OpenAlex technical documentation](#author-object-openalex-technical-documentation) - [Get lists of entities | OpenAlex technical documentation](#get-lists-of-entities-openalex-technical-documentation) - [Tutorials | OpenAlex technical documentation](#tutorials-openalex-technical-documentation) - [Random result | OpenAlex technical documentation](#random-result-openalex-technical-documentation) - [Search concepts | OpenAlex technical documentation](#search-concepts-openalex-technical-documentation) - [API Overview | OpenAlex technical documentation](#api-overview-openalex-technical-documentation) - [Get lists of institutions | OpenAlex technical documentation](#get-lists-of-institutions-openalex-technical-documentation) - [Group concepts | OpenAlex technical documentation](#group-concepts-openalex-technical-documentation) - [Get lists of funders | OpenAlex technical documentation](#get-lists-of-funders-openalex-technical-documentation) - [Group awards | OpenAlex technical documentation](#group-awards-openalex-technical-documentation) - [Search awards | OpenAlex technical documentation](#search-awards-openalex-technical-documentation) - [xpac | OpenAlex technical documentation](#xpac-openalex-technical-documentation) - [Upload to your database | OpenAlex technical documentation](#upload-to-your-database-openalex-technical-documentation) - [Report bugs | OpenAlex technical documentation](#report-bugs-openalex-technical-documentation) - [Sort entity lists | OpenAlex technical documentation](#sort-entity-lists-openalex-technical-documentation) - [Funder object | OpenAlex technical documentation](#funder-object-openalex-technical-documentation) - [Rate limits and authentication | OpenAlex technical documentation](#rate-limits-and-authentication-openalex-technical-documentation) - [Search funders | OpenAlex technical documentation](#search-funders-openalex-technical-documentation) - [Concepts | OpenAlex technical documentation](#concepts-openalex-technical-documentation) - [Download to your machine | OpenAlex technical documentation](#download-to-your-machine-openalex-technical-documentation) - [Filter awards | OpenAlex technical documentation](#filter-awards-openalex-technical-documentation) - [Postgres schema diagram | OpenAlex technical documentation](#postgres-schema-diagram-openalex-technical-documentation) - [Source object | OpenAlex technical documentation](#source-object-openalex-technical-documentation) - [Award object | OpenAlex technical documentation](#award-object-openalex-technical-documentation) - [Publisher object | OpenAlex technical documentation](#publisher-object-openalex-technical-documentation) - [Filter funders | OpenAlex technical documentation](#filter-funders-openalex-technical-documentation) - [Sample entity lists | OpenAlex technical documentation](#sample-entity-lists-openalex-technical-documentation) - [Get a single concept | OpenAlex technical documentation](#get-a-single-concept-openalex-technical-documentation) - [OpenAlex snapshot | OpenAlex technical documentation](#openalex-snapshot-openalex-technical-documentation) - [Select fields | OpenAlex technical documentation](#select-fields-openalex-technical-documentation) - [Get lists of awards | OpenAlex technical documentation](#get-lists-of-awards-openalex-technical-documentation) - [Get lists of concepts | OpenAlex technical documentation](#get-lists-of-concepts-openalex-technical-documentation) - [FAQ | OpenAlex technical documentation](#faq-openalex-technical-documentation) - [Paging | OpenAlex technical documentation](#paging-openalex-technical-documentation) - [Concept object | OpenAlex technical documentation](#concept-object-openalex-technical-documentation) - [Search entities | OpenAlex technical documentation](#search-entities-openalex-technical-documentation) - [Autocomplete entities | OpenAlex technical documentation](#autocomplete-entities-openalex-technical-documentation) - [Snapshot data format | OpenAlex technical documentation](#snapshot-data-format-openalex-technical-documentation) - [Get single entities | OpenAlex technical documentation](#get-single-entities-openalex-technical-documentation) - [Filter concepts | OpenAlex technical documentation](#filter-concepts-openalex-technical-documentation) - [Load to a relational database | OpenAlex technical documentation](#load-to-a-relational-database-openalex-technical-documentation) - [Get groups of entities | OpenAlex technical documentation](#get-groups-of-entities-openalex-technical-documentation) - [Load to a data warehouse | OpenAlex technical documentation](#load-to-a-data-warehouse-openalex-technical-documentation) - [Institution object | OpenAlex technical documentation](#institution-object-openalex-technical-documentation) - [Filter entity lists | OpenAlex technical documentation](#filter-entity-lists-openalex-technical-documentation) - [Work object | OpenAlex technical documentation](#work-object-openalex-technical-documentation) - [Filter works | OpenAlex technical documentation](#filter-works-openalex-technical-documentation) - [Email Protection | Cloudflare](#email-protection-cloudflare) --- # Overview | OpenAlex technical documentation [**OpenAlex**](https://openalex.org/) is a fully open catalog of the global research system. It's named after the [ancient Library of Alexandria](https://en.wikipedia.org/wiki/Library_of_Alexandria) and made by the nonprofit [OurResearch](https://ourresearch.org/) . This is the **technical documentation for OpenAlex,** including the [**OpenAlex API**](https://docs.openalex.org/how-to-use-the-api/api-overview) and the [**data snapshot**](https://docs.openalex.org/download-all-data/openalex-snapshot) **.** Here, you can learn how to set up your code to access OpenAlex's data. If you want to explore the data as a human, you may be more interested in [**OpenAlex Web**](https://help.openalex.org/) **.** [](https://docs.openalex.org/#data) Data --------------------------------------------- The OpenAlex dataset describes scholarly [_entities_](https://docs.openalex.org/api-entities/entities-overview) and how those entities are connected to each other. Types of entities include [works](https://docs.openalex.org/api-entities/works) , [authors](https://docs.openalex.org/api-entities/authors) , [sources](https://docs.openalex.org/api-entities/sources) , [institutions](https://docs.openalex.org/api-entities/institutions) , [topics](https://docs.openalex.org/api-entities/topics) , [publishers](https://docs.openalex.org/api-entities/publishers) , and [funders](https://docs.openalex.org/api-entities/funders) . Together, these make a huge web (or more technically, heterogeneous directed [graph](https://en.wikipedia.org/wiki/Graph_theory) ) of hundreds of millions of entities and billions of connections between them all. Learn more at our general help center article: [About the data](https://help.openalex.org/hc/en-us/articles/24397285563671-About-the-data) [](https://docs.openalex.org/#access) Access ------------------------------------------------- We offer a fast, modern REST API to get OpenAlex data programmatically. It's free and requires no authentication. The daily limit for API calls is 100,000 requests per user per day. For best performance, [add your email](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool) to all API requests, like `mailto=example@domain.com`. [Learn more](https://docs.openalex.org/how-to-use-the-api/api-overview) There is also a complete database snapshot available to download. [Learn more about the data snapshot here.](https://docs.openalex.org/download-all-data/openalex-snapshot) The API has a limit of 100,000 calls per day, and the snapshot is updated monthly. If you need a higher limit, or more frequent updates, please look into [**OpenAlex Premium.**](https://openalex.org/pricing) The web interface for OpenAlex, built directly on top of the API, is the quickest and easiest way to [get started with OpenAlex](https://help.openalex.org/getting-started) . [](https://docs.openalex.org/#why-openalex) Why OpenAlex? -------------------------------------------------------------- OpenAlex offers an open replacement for industry-standard scientific knowledge bases like Elsevier's Scopus and Clarivate's Web of Science. [Compared to](https://openalex.org/about#comparison) these paywalled services, OpenAlex offers significant advantages in terms of inclusivity, affordability, and avaliability. OpenAlex is: * _Big —_ We have about twice the coverage of the other services, and have significantly better coverage of non-English works and works from the Global South. * _Easy —_ Our service is fast, modern, and well-documented. * _Open —_ Our complete dataset is free under the CC0 license, which allows for transparency and reuse. Many people and organizations have already found great value using OpenAlex. Have a look at the [Testimonials](https://openalex.org/testimonials) to hear what they've said! [](https://docs.openalex.org/#contact) Contact --------------------------------------------------- For tech support and bug reports, please visit our [help page](https://openalex.org/help) . You can also join the [OpenAlex user group](https://groups.google.com/g/openalex-users) , and follow us on [Twitter (@OpenAlex\_org)](https://twitter.com/openalex_org) and [Mastodon](https://mastodon.social/@OpenAlex) . [](https://docs.openalex.org/#citation) Citation ----------------------------------------------------- If you use OpenAlex in research, please cite [this paper](https://arxiv.org/abs/2205.01833) : > Priem, J., Piwowar, H., & Orr, R. (2022). _OpenAlex: A fully-open index of scholarly works, authors, venues, institutions, and concepts_. ArXiv. https://arxiv.org/abs/2205.01833 [NextAPI Guide for LLMs](https://docs.openalex.org/api-guide-for-llms) Last updated 22 days ago --- # API Guide for LLMs | OpenAlex technical documentation [](https://docs.openalex.org/api-guide-for-llms#openalex-api-guide-for-llm-agents-and-ai-applications) OpenAlex API Guide for LLM Agents and AI Applications ----------------------------------------------------------------------------------------------------------------------------------------------------------------- OpenAlex is a fully open catalog of scholarly works, authors, sources, institutions, topics, publishers, and funders. Base URL: https://api.openalex.org Documentation: https://docs.openalex.org No authentication required | 100,000 requests/day limit ### [](https://docs.openalex.org/api-guide-for-llms#critical-gotchas-read-these-first) CRITICAL GOTCHAS - Read These First! #### [](https://docs.openalex.org/api-guide-for-llms#dont-create-a-d-hoc-sampling-by-using-random-page-numbers) ❌ DON'T: Create ad-hoc sampling by using random page numbers WRONG: ?page=5, ?page=17, ?page=42 to get "random" results This is NOT random sampling and will bias your results! #### [](https://docs.openalex.org/api-guide-for-llms#do-use-the-sample-parameter-for-random-sampling) ✅ DO: Use the ?sample parameter for random sampling CORRECT: https://api.openalex.org/works?sample=20 For consistent results, add a seed: ?sample=20&seed=123 #### [](https://docs.openalex.org/api-guide-for-llms#dont-try-to-sample-large-datasets-10k-in-one-request) ❌ DON'T: Try to sample large datasets (10k+) in one request The sample parameter maxes out at reasonable sizes for a single request. #### [](https://docs.openalex.org/api-guide-for-llms#do-use-multiple-samples-with-different-seeds-then-deduplicate) ✅ DO: Use multiple samples with different seeds, then deduplicate For large random samples (10k+ records): 1. Make multiple sample requests with different seeds 2. Combine results 3. Deduplicate by ID Example: * ?sample=1000&seed=1 * ?sample=1000&seed=2 * ?sample=1000&seed=3 Then deduplicate the combined results by checking work IDs. See: https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists #### [](https://docs.openalex.org/api-guide-for-llms#dont-search-filter-by-entity-names-directly) ❌ DON'T: Search/filter by entity names directly WRONG: /works?filter=author\_name:Einstein Entity names are ambiguous and this won't work! #### [](https://docs.openalex.org/api-guide-for-llms#do-use-two-step-lookup-pattern-for-related-entities) ✅ DO: Use two-step lookup pattern for related entities CORRECT two-step process: 1. Find the entity ID: /authors?search=einstein Response shows ID like "A5023888391" or full URI 2. Use ID to filter: /works?filter=authorships.author.id:A5023888391 Why? Names are ambiguous. "MIT" could be many institutions. IDs are unique. This applies to: authors, institutions, sources, topics, publishers, funders. #### [](https://docs.openalex.org/api-guide-for-llms#dont-try-to-group-by-multiple-dimensions-in-one-query) ❌ DON'T: Try to group by multiple dimensions in one query WRONG: You cannot do SQL-style "GROUP BY topic, year" in a single API call. #### [](https://docs.openalex.org/api-guide-for-llms#do-make-multiple-queries-and-combine-results-client-side) ✅ DO: Make multiple queries and combine results client-side To analyze by topic AND year (or any two dimensions): 1. Make one query per year: ?filter=publication\_year:2020&group\_by=topics.id 2. Repeat for 2021, 2022, etc. 3. Combine results in your code The API only supports one group\_by per request. #### [](https://docs.openalex.org/api-guide-for-llms#dont-ignore-api-errors-or-retry-immediately-on-failure) ❌ DON'T: Ignore API errors or retry immediately on failure API errors are common, especially at scale. Immediate retries can make things worse. #### [](https://docs.openalex.org/api-guide-for-llms#do-implement-exponential-backoff-for-retries) ✅ DO: Implement exponential backoff for retries When you get errors (429 rate limit, 500 server error, timeouts): 1. Catch the error 2. Wait before retrying (1s, 2s, 4s, 8s, etc.) 3. Include a max retry limit (e.g., 5 attempts) 4. Log failures for debugging #### [](https://docs.openalex.org/api-guide-for-llms#dont-use-default-page-sizes-for-bulk-extraction) ❌ DON'T: Use default page sizes for bulk extraction Default is only 25 results per page. Slow for large extracts! #### [](https://docs.openalex.org/api-guide-for-llms#do-use-maximum-page-size-200-for-bulk-data-extraction) ✅ DO: Use maximum page size (200) for bulk data extraction FAST: ?per-page=200 This reduces the number of API calls needed by 8x compared to default. #### [](https://docs.openalex.org/api-guide-for-llms#dont-make-sequential-api-calls-for-lists-of-known-ids) ❌ DON'T: Make sequential API calls for lists of known IDs SLOW: Loop through 100 DOIs making 100 separate API calls. #### [](https://docs.openalex.org/api-guide-for-llms#do-use-the-or-filter-pipe-or-for-batch-id-lookups) ✅ DO: Use the OR filter (pipe |) for batch ID lookups FAST: Combine up to 50 IDs in one query using pipe separator: /works?filter=doi:https://doi.org/10.1371/journal.pone.0266781|https://doi.org/10.1371/journal.pone.0267149|... You can include up to 50 values per filter. Use per-page=50 to get all results. See: https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or #### [](https://docs.openalex.org/api-guide-for-llms#dont-ignore-rate-limits-when-using-concurrency-threading) ❌ DON'T: Ignore rate limits when using concurrency/threading Using multiple threads WITHOUT respecting rate limits will get you rate-limited or banned. #### [](https://docs.openalex.org/api-guide-for-llms#do-respect-rate-limits-even-across-concurrent-requests) ✅ DO: Respect rate limits even across concurrent requests * Default pool: 1 request/second * Polite pool (with email): 10 requests/second * Daily limit: 100,000 requests When using threading/async: 1. Implement rate limiting across ALL threads 2. Track requests per second globally 3. Add your email to requests for 10x higher limits ### [](https://docs.openalex.org/api-guide-for-llms#quick-reference) Quick Reference #### [](https://docs.openalex.org/api-guide-for-llms#base-url-and-authentication) Base URL and Authentication #### [](https://docs.openalex.org/api-guide-for-llms#get-higher-rate-limits-polite-pool) Get Higher Rate Limits (Polite Pool) Add your email to ANY parameter: This increases your rate limit from 1 req/sec → 10 req/sec Always do this for production applications! #### [](https://docs.openalex.org/api-guide-for-llms#entity-endpoints) Entity Endpoints #### [](https://docs.openalex.org/api-guide-for-llms#essential-query-parameters) Essential Query Parameters ### [](https://docs.openalex.org/api-guide-for-llms#filter-syntax) Filter Syntax #### [](https://docs.openalex.org/api-guide-for-llms#basic-filtering) Basic Filtering #### [](https://docs.openalex.org/api-guide-for-llms#comparison-operators) Comparison Operators #### [](https://docs.openalex.org/api-guide-for-llms#multiple-values-in-same-attribute) Multiple Values in Same Attribute You can express AND within a single attribute two ways: Both mean: "works with author from US AND author from GB" #### [](https://docs.openalex.org/api-guide-for-llms#or-queries-pipe-separator) OR Queries (Pipe Separator) You can combine up to 50 values with pipes. #### [](https://docs.openalex.org/api-guide-for-llms#important-or-only-works-within-a-filter-not-between-filters) Important: OR only works WITHIN a filter, not BETWEEN filters ### [](https://docs.openalex.org/api-guide-for-llms#common-patterns) Common Patterns #### [](https://docs.openalex.org/api-guide-for-llms#get-random-sample-of-works) Get Random Sample of Works #### [](https://docs.openalex.org/api-guide-for-llms#search-works-by-title-abstract) Search Works by Title/Abstract #### [](https://docs.openalex.org/api-guide-for-llms#find-works-by-author-two-step-pattern) Find Works by Author (Two-Step Pattern) #### [](https://docs.openalex.org/api-guide-for-llms#find-works-by-institution-two-step-pattern) Find Works by Institution (Two-Step Pattern) #### [](https://docs.openalex.org/api-guide-for-llms#get-highly-cited-recent-papers) Get Highly Cited Recent Papers #### [](https://docs.openalex.org/api-guide-for-llms#get-open-access-works-only) Get Open Access Works Only #### [](https://docs.openalex.org/api-guide-for-llms#filter-by-multiple-criteria) Filter by Multiple Criteria #### [](https://docs.openalex.org/api-guide-for-llms#bulk-lookup-by-dois) Bulk Lookup by DOIs #### [](https://docs.openalex.org/api-guide-for-llms#get-works-from-specific-journal) Get Works from Specific Journal #### [](https://docs.openalex.org/api-guide-for-llms#aggregate-group-data) Aggregate/Group Data #### [](https://docs.openalex.org/api-guide-for-llms#pagination-for-large-result-sets) Pagination for Large Result Sets #### [](https://docs.openalex.org/api-guide-for-llms#select-specific-fields-only-faster-responses) Select Specific Fields Only (Faster Responses) #### [](https://docs.openalex.org/api-guide-for-llms#autocomplete-for-type-ahead) Autocomplete for Type-Ahead #### [](https://docs.openalex.org/api-guide-for-llms#tag-your-own-text-text-endpoint) Tag Your Own Text (/text endpoint) ### [](https://docs.openalex.org/api-guide-for-llms#response-structure) Response Structure #### [](https://docs.openalex.org/api-guide-for-llms#list-endpoints) List Endpoints All list endpoints (/works, /authors, etc.) return: #### [](https://docs.openalex.org/api-guide-for-llms#single-entity-endpoints) Single Entity Endpoints Getting a single entity returns the object directly: #### [](https://docs.openalex.org/api-guide-for-llms#group-by-responses) Group By Responses ### [](https://docs.openalex.org/api-guide-for-llms#performance-optimization-tips) Performance Optimization Tips #### [](https://docs.openalex.org/api-guide-for-llms#id-1.-use-maximum-page-size) 1\. Use Maximum Page Size #### [](https://docs.openalex.org/api-guide-for-llms#id-2.-use-batch-id-lookups) 2\. Use Batch ID Lookups #### [](https://docs.openalex.org/api-guide-for-llms#id-3.-select-only-fields-you-need) 3\. Select Only Fields You Need #### [](https://docs.openalex.org/api-guide-for-llms#id-4.-use-concurrent-requests-with-rate-limiting) 4\. Use Concurrent Requests with Rate Limiting #### [](https://docs.openalex.org/api-guide-for-llms#id-5.-add-email-for-10x-speed-boost) 5\. Add Email for 10x Speed Boost ### [](https://docs.openalex.org/api-guide-for-llms#handling-errors) Handling Errors #### [](https://docs.openalex.org/api-guide-for-llms#common-http-status-codes) Common HTTP Status Codes #### [](https://docs.openalex.org/api-guide-for-llms#exponential-backoff-pattern) Exponential Backoff Pattern ### [](https://docs.openalex.org/api-guide-for-llms#entity-specific-filter-examples) Entity-Specific Filter Examples #### [](https://docs.openalex.org/api-guide-for-llms#works-filters-most-common) Works Filters (Most Common) #### [](https://docs.openalex.org/api-guide-for-llms#authors-filters) Authors Filters #### [](https://docs.openalex.org/api-guide-for-llms#sources-filters) Sources Filters #### [](https://docs.openalex.org/api-guide-for-llms#institutions-filters) Institutions Filters ### [](https://docs.openalex.org/api-guide-for-llms#external-id-support) External ID Support You can use external IDs directly in the API: #### [](https://docs.openalex.org/api-guide-for-llms#works) Works #### [](https://docs.openalex.org/api-guide-for-llms#authors) Authors #### [](https://docs.openalex.org/api-guide-for-llms#institutions) Institutions #### [](https://docs.openalex.org/api-guide-for-llms#sources) Sources ### [](https://docs.openalex.org/api-guide-for-llms#advanced-tips) Advanced Tips #### [](https://docs.openalex.org/api-guide-for-llms#reproducible-random-samples) Reproducible Random Samples Always use a seed for reproducible sampling: Same seed = same results every time. #### [](https://docs.openalex.org/api-guide-for-llms#finding-related-works) Finding Related Works #### [](https://docs.openalex.org/api-guide-for-llms#filtering-by-date-ranges) Filtering by Date Ranges #### [](https://docs.openalex.org/api-guide-for-llms#complex-boolean-searches) Complex Boolean Searches The search parameter supports boolean operators: ### [](https://docs.openalex.org/api-guide-for-llms#rate-limiting-best-practices) Rate Limiting Best Practices #### [](https://docs.openalex.org/api-guide-for-llms#without-email-default-pool) Without Email (Default Pool) * 1 request per second * 100,000 requests per day * Sequential processing recommended #### [](https://docs.openalex.org/api-guide-for-llms#with-email-polite-pool) With Email (Polite Pool) * 10 requests per second * 100,000 requests per day * Parallel processing viable * **Always include your email for production use** #### [](https://docs.openalex.org/api-guide-for-llms#concurrent-requests-strategy) Concurrent Requests Strategy #### [](https://docs.openalex.org/api-guide-for-llms#daily-limit-management) Daily Limit Management With 100k/day limit: * ~4,166 requests per hour average * ~69 requests per minute average * Plan accordingly for large jobs * Consider OpenAlex Premium for higher limits ### [](https://docs.openalex.org/api-guide-for-llms#common-mistakes-to-avoid) Common Mistakes to Avoid 1. ❌ Using page numbers for sampling → ✅ Use ?sample= 2. ❌ Filtering by entity names → ✅ Get IDs first, then filter 3. ❌ Default page size → ✅ Use per-page=200 4. ❌ Sequential ID lookups → ✅ Batch with pipe (|) operator 5. ❌ No error handling → ✅ Implement retry with backoff 6. ❌ Ignoring rate limits in threads → ✅ Global rate limiting 7. ❌ Trying to group by multiple fields → ✅ Multiple queries + combine 8. ❌ Not including email → ✅ Add mailto= for 10x speed 9. ❌ Fetching all fields → ✅ Use select= for needed fields only 10. ❌ Assuming instant responses → ✅ Add timeouts (30s recommended) ### [](https://docs.openalex.org/api-guide-for-llms#need-more-info) Need More Info? * Full documentation: https://docs.openalex.org * API Overview: https://docs.openalex.org/how-to-use-the-api/api-overview * Entity schemas: https://docs.openalex.org/api-entities * Help: https://openalex.org/help * User group: https://groups.google.com/g/openalex-users ### [](https://docs.openalex.org/api-guide-for-llms#for-premium-features) For Premium Features If you need: * More than 100k requests/day * Faster than daily snapshot updates * Commercial support * SLA guarantees See: https://openalex.org/pricing * * * Last updated: 2025-10-13 Maintained for: LLM agents, AI applications, and automated tools [PreviousOverview](https://docs.openalex.org/) [NextQuickstart tutorial](https://docs.openalex.org/quickstart-tutorial) Last updated 22 days ago * [OpenAlex API Guide for LLM Agents and AI Applications](https://docs.openalex.org/api-guide-for-llms#openalex-api-guide-for-llm-agents-and-ai-applications) * [CRITICAL GOTCHAS - Read These First!](https://docs.openalex.org/api-guide-for-llms#critical-gotchas-read-these-first) * [Quick Reference](https://docs.openalex.org/api-guide-for-llms#quick-reference) * [Filter Syntax](https://docs.openalex.org/api-guide-for-llms#filter-syntax) * [Common Patterns](https://docs.openalex.org/api-guide-for-llms#common-patterns) * [Response Structure](https://docs.openalex.org/api-guide-for-llms#response-structure) * [Performance Optimization Tips](https://docs.openalex.org/api-guide-for-llms#performance-optimization-tips) * [Handling Errors](https://docs.openalex.org/api-guide-for-llms#handling-errors) * [Entity-Specific Filter Examples](https://docs.openalex.org/api-guide-for-llms#entity-specific-filter-examples) * [External ID Support](https://docs.openalex.org/api-guide-for-llms#external-id-support) * [Advanced Tips](https://docs.openalex.org/api-guide-for-llms#advanced-tips) * [Rate Limiting Best Practices](https://docs.openalex.org/api-guide-for-llms#rate-limiting-best-practices) * [Common Mistakes to Avoid](https://docs.openalex.org/api-guide-for-llms#common-mistakes-to-avoid) * [Need More Info?](https://docs.openalex.org/api-guide-for-llms#need-more-info) * [For Premium Features](https://docs.openalex.org/api-guide-for-llms#for-premium-features) Copy Base: https://api.openalex.org Auth: None required Rate: 100k requests/day Copy https://api.openalex.org/[email protected] Copy /works - 240M+ scholarly documents (articles, books, datasets) /authors - Researcher profiles with disambiguated identities /sources - Journals, repositories, conferences /institutions - Universities, research organizations /topics - Subject classifications (3-level hierarchy) /publishers - Publishing organizations /funders - Funding agencies /text - Tag your own text with OpenAlex topics/keywords (POST) Copy filter= - Filter results (see filter syntax below) search= - Full-text search across title/abstract/fulltext sort= - Sort results (e.g., cited_by_count:desc) per-page= - Results per page (default: 25, max: 200) page= - Page number for pagination sample= - Get random results (e.g., sample=50) seed= - Seed for reproducible sampling select= - Limit returned fields (e.g., select=id,title) group_by= - Aggregate results by a field mailto= - Your email (gets you into polite pool) Copy Single filter: ?filter=publication_year:2020 Multiple (AND): ?filter=publication_year:2020,is_oa:true Values (OR): ?filter=type:journal-article|book Negation: ?filter=type:!journal-article Copy Greater than: ?filter=cited_by_count:>100 Less than: ?filter=publication_year:<2020 Range: ?filter=publication_year:2020-2023 Copy Repeat filter: ?filter=institutions.country_code:us,institutions.country_code:gb Use + symbol: ?filter=institutions.country_code:us+gb Copy Any of these: ?filter=institutions.country_code:us|gb|ca Batch IDs: ?filter=doi:10.1/abc|10.2/def|10.3/ghi Copy POSSIBLE: ?filter=type:article|book (article OR book) NOT POSSIBLE: Cannot do "(year=2020 OR year=2021) AND (type=article)" WORKAROUND: Make separate queries and combine results Copy Small sample: https://api.openalex.org/works?sample=20 Reproducible sample: https://api.openalex.org/works?sample=20&seed=42 Large sample (10k+): 1. https://api.openalex.org/works?sample=1000&seed=1 2. https://api.openalex.org/works?sample=1000&seed=2 3. https://api.openalex.org/works?sample=1000&seed=3 ...then deduplicate by ID Copy Simple search: https://api.openalex.org/works?search=machine+learning Search specific field: https://api.openalex.org/works?filter=title.search:CRISPR Search + filter: https://api.openalex.org/works?search=climate&filter=publication_year:2023 Copy Step 1 - Get author ID: https://api.openalex.org/authors?search=Heather+Piwowar Response includes: "id": "https://openalex.org/A5023888391" Step 2 - Get their works: https://api.openalex.org/works?filter=authorships.author.id:A5023888391 Alternative - Use ORCID directly: https://api.openalex.org/works?filter=authorships.author.id:https://orcid.org/0000-0003-1613-5981 Copy Step 1 - Get institution ID: https://api.openalex.org/institutions?search=MIT Response includes: "id": "https://openalex.org/I136199984" Step 2 - Get their works: https://api.openalex.org/works?filter=authorships.institutions.id:I136199984 Alternative - Use ROR directly: https://api.openalex.org/works?filter=authorships.institutions.id:https://ror.org/042nb2s44 Copy https://api.openalex.org/works?filter=publication_year:>2020&sort=cited_by_count:desc&per-page=200 Copy All OA: https://api.openalex.org/works?filter=is_oa:true Gold OA only: https://api.openalex.org/works?filter=open_access.oa_status:gold Published OA version: https://api.openalex.org/works?filter=has_oa_published_version:true Copy Recent OA works about COVID from top institutions: https://api.openalex.org/works?filter=publication_year:2022,is_oa:true,title.search:covid,authorships.institutions.id:I136199984|I27837315 Breaking down the filters: - publication_year:2022 (recent) - is_oa:true (open access) - title.search:covid (about COVID) - authorships.institutions.id:I136199984|I27837315 (MIT or Harvard) Copy Get specific works by DOI (efficient batch method): https://api.openalex.org/works?filter=doi:https://doi.org/10.1371/journal.pone.0266781|https://doi.org/10.1371/journal.pone.0267149|https://doi.org/10.1371/journal.pone.0267890&per-page=50 Up to 50 DOIs per request. Use per-page=50 to ensure you get all results. Copy Step 1 - Get source ID: https://api.openalex.org/sources?search=Nature Response includes: "id": "https://openalex.org/S137773608" Step 2 - Get works from that source: https://api.openalex.org/works?filter=primary_location.source.id:S137773608 Copy Top topics by work count: https://api.openalex.org/works?group_by=topics.id Papers per year: https://api.openalex.org/works?group_by=publication_year Most prolific institutions: https://api.openalex.org/works?group_by=authorships.institutions.id Group with filters: https://api.openalex.org/works?filter=publication_year:>2020&group_by=topics.id Copy First page: https://api.openalex.org/works?filter=publication_year:2023&per-page=200 Next pages: https://api.openalex.org/works?filter=publication_year:2023&per-page=200&page=2 https://api.openalex.org/works?filter=publication_year:2023&per-page=200&page=3 ... The meta.count field tells you total results. Calculate pages needed: ceil(meta.count / per-page) Copy Just IDs and titles: https://api.openalex.org/works?select=id,title&per-page=200 Multiple fields: https://api.openalex.org/works?select=id,title,publication_year,cited_by_count Copy Fast autocomplete endpoint for building search UIs: Authors: https://api.openalex.org/autocomplete/authors?q=einst Institutions: https://api.openalex.org/autocomplete/institutions?q=stanford Works: https://api.openalex.org/autocomplete/works?q=neural+networks Typically returns in ~200ms Copy POST or GET to classify your own content: https://api.openalex.org/text?title=Machine+learning+for+drug+discovery Returns topics, keywords, and concepts for your text. Limited to 1 req/sec and 1000 req/day. Text must be 20-2000 characters. Copy { "meta": { "count": 240523418, "db_response_time_ms": 42, "page": 1, "per_page": 25 }, "results": [\ { /* entity object */ },\ { /* entity object */ },\ ...\ ] } Copy https://api.openalex.org/works/W2741809807 → Returns a Work object directly (no meta/results wrapper) Copy { "meta": { "count": 100, ... }, "group_by": [\ {\ "key": "https://openalex.org/T10001",\ "key_display_name": "Artificial Intelligence",\ "count": 15234\ },\ ...\ ] } Copy SLOW: Default 25 per page = more API calls FAST: ?per-page=200 (8x fewer API calls) Copy SLOW: Loop through 50 DOIs, 50 API calls FAST: One call with pipe-separated DOIs (up to 50) Copy SLOW: Full objects with all fields FAST: ?select=id,title,publication_year Copy # Pseudo-code from concurrent.futures import ThreadPoolExecutor import time rate_limiter = RateLimiter(10) # 10 req/sec with polite pool def fetch_page(page_num): rate_limiter.wait() # Ensure we don't exceed rate limit return requests.get(f"...&page={page_num}&[email protected]") with ThreadPoolExecutor(max_workers=10) as executor: results = executor.map(fetch_page, range(1, 101)) Copy WITHOUT: 1 request/second max WITH: 10 requests/second max Just add: &[email protected] Copy 200 OK - Success 400 Bad Request - Invalid parameter (check your filter syntax) 403 Forbidden - Rate limit exceeded (slow down, implement backoff) 404 Not Found - Entity doesn't exist 500 Server Error - Temporary issue (retry with backoff) Copy def fetch_with_retry(url, max_retries=5): for attempt in range(max_retries): try: response = requests.get(url, timeout=30) if response.status_code == 200: return response.json() elif response.status_code == 403: # Rate limited wait_time = 2 ** attempt # 1s, 2s, 4s, 8s, 16s time.sleep(wait_time) elif response.status_code >= 500: # Server error wait_time = 2 ** attempt time.sleep(wait_time) else: # Other error, don't retry response.raise_for_status() except requests.exceptions.Timeout: if attempt < max_retries - 1: time.sleep(2 ** attempt) else: raise raise Exception(f"Failed after {max_retries} retries") Copy authorships.author.id - Author's OpenAlex ID authorships.institutions.id - Institution's OpenAlex ID cited_by_count - Number of citations is_oa - Is open access (true/false) publication_year - Year published primary_location.source.id - Source (journal) ID topics.id - Topic ID type - article, book, dataset, etc. has_doi - Has a DOI (true/false) has_fulltext - Has fulltext available (true/false) Copy last_known_institution.id - Current/last institution works_count - Number of works authored cited_by_count - Total citations orcid - ORCID identifier Copy host_organization - Publisher/host type - journal, repository, etc. is_oa - Is open access Copy type - education, healthcare, company, etc. country_code - Two-letter country code continent - africa, asia, europe, etc. Copy DOI: /works/https://doi.org/10.7717/peerj.4375 PMID: /works/pmid:29844763 Copy ORCID: /authors/https://orcid.org/0000-0003-1613-5981 Copy ROR: /institutions/https://ror.org/02y3ad647 Copy ISSN: /sources/issn:0028-0836 Copy https://api.openalex.org/works?sample=100&seed=42 Copy Get cited works: 1. Get work: /works/W2741809807 2. Response includes: "referenced_works": [...] 3. Fetch those: /works?filter=openalex_id:W123|W456|W789 Get citing works: 1. Get work: /works/W2741809807 2. Response includes: "cited_by_api_url" 3. Follow that URL Copy Exact year: ?filter=publication_year:2020 After: ?filter=publication_year:>2020 Before: ?filter=publication_year:<2020 Range: ?filter=publication_year:2018-2022 Copy AND: ?search=climate+AND+change OR: ?search=climate+OR+weather NOT: ?search=climate+NOT+politics Copy 1. Track requests per second globally (not per thread) 2. Use a semaphore or rate limiter across threads 3. Add delays between batches if needed 4. Monitor for 403 responses (rate limit exceeded) 5. Back off if you hit limits --- # Quickstart tutorial | OpenAlex technical documentation Lets use the OpenAlex API to get journal articles and books published by authors at Stanford University. We'll limit our search to articles published between 2010 and 2020. Since OpenAlex is free and openly available, these examples work without any login or account creation. 👍 If you open these examples in a web browser, they will look _much_ better if you have a browser plug-in such as [JSONVue](https://chrome.google.com/webstore/detail/jsonvue/chklaanhfefbnpoihckbnefhakgolnmc) installed. ### [](https://docs.openalex.org/quickstart-tutorial#id-1.-find-the-institution) 1\. Find the institution You can use the [institutions](https://docs.openalex.org/api-entities/institutions) endpoint to learn about universities and research centers. OpenAlex has a powerful search feature that searches across 108,000 institutions. Lets use it to search for Stanford University: * Find Stanford University [`https://api.openalex.org/institutions?search=stanford`](https://api.openalex.org/institutions?search=stanford) Our first result looks correct (yeah!): Copy { "id": "https://openalex.org/I97018004", "ror": "https://ror.org/00f54p054", "display_name": "Stanford University", "country_code": "US", "type": "education", "homepage_url": "http://www.stanford.edu/" // other fields removed } We can use the ID `https://openalex.org/I97018004` in that result to find out more. ### [](https://docs.openalex.org/quickstart-tutorial#id-2.-find-articles-works-associated-with-stanford-university) 2\. Find articles (works) associated with Stanford University The [works](https://docs.openalex.org/api-entities/works) endpoint contains over 240 million articles, books, and theses 😲. We can filter to show works associated with Stanford. * Show works where at least one author is associated with Stanford University [`https://api.openalex.org/works?filter=institutions.id:https://openalex.org/I97018004`](https://api.openalex.org/works?filter=institutions.id:https://openalex.org/I97018004) This is just one of the 50+ ways that you can filter works! ### [](https://docs.openalex.org/quickstart-tutorial#id-3.-filter-works-by-publication-year) 3\. Filter works by publication year Right now the list shows records for all years. Lets narrow it down to works that were published between 2010 to 2020, and sort from newest to oldest. * Show works with publication years 2010 to 2020, associated with Stanford University [https://api.openalex.org/works?filter=institutions.id:https://openalex.org/I97018004,publication\_year:2010-2020&sort=publication\_date:desc](https://api.openalex.org/works?filter=institutions.id:https://openalex.org/I97018004,publication_year:2010-2020&sort=publication_date:desc) ### [](https://docs.openalex.org/quickstart-tutorial#id-4.-group-works-by-publication-year-to-show-counts-by-year) 4\. Group works by publication year to show counts by year Finally, you can group our result by publication year to get our final result, which is the number of articles produced by Stanford, by year from 2010 to 2020. There are more than 30 ways to group records in OpenAlex, including by publisher, journal, and open access status. * Group records by publication year [`https://api.openalex.org/works?filter=institutions.id:https://openalex.org/I97018004,publication\_year:2010-2020\&group-by=publication\_year`](https://api.openalex.org/works?filter=institutions.id:https://openalex.org/I97018004,publication_year:2010-2020&group-by=publication_year) That gives a result like this: There you have it! This same technique can be applied to hundreds of questions around scholarly data. The data you received is under a [CC0 license](https://creativecommons.org/publicdomain/zero/1.0/) , so not only did you access it easily, you can share it freely! 🎉 [](https://docs.openalex.org/quickstart-tutorial#whats-next) What's next? ------------------------------------------------------------------------------ Jump into an area of OpenAlex that interests you: * [Works](https://docs.openalex.org/api-entities/works) * [Authors](https://docs.openalex.org/api-entities/authors) * [Sources](https://docs.openalex.org/api-entities/sources) * [Institutions](https://docs.openalex.org/api-entities/institutions) * [Topics](https://docs.openalex.org/api-entities/topics) * [Publishers](https://docs.openalex.org/api-entities/publishers) * [Funders](https://docs.openalex.org/api-entities/funders) And check out our [tutorials](https://docs.openalex.org/additional-help/tutorials) page for some hands-on examples! [PreviousAPI Guide for LLMs](https://docs.openalex.org/api-guide-for-llms) [NextEntities overview](https://docs.openalex.org/api-entities/entities-overview) Last updated 22 days ago * [1\. Find the institution](https://docs.openalex.org/quickstart-tutorial#id-1.-find-the-institution) * [2\. Find articles (works) associated with Stanford University](https://docs.openalex.org/quickstart-tutorial#id-2.-find-articles-works-associated-with-stanford-university) * [3\. Filter works by publication year](https://docs.openalex.org/quickstart-tutorial#id-3.-filter-works-by-publication-year) * [4\. Group works by publication year to show counts by year](https://docs.openalex.org/quickstart-tutorial#id-4.-group-works-by-publication-year-to-show-counts-by-year) * [What's next?](https://docs.openalex.org/quickstart-tutorial#whats-next) Copy [\ {\ "key": "2020",\ "key_display_name": "2020",\ "count": 18627\ },\ {\ "key": "2019",\ "key_display_name": "2019",\ "count": 15933\ },\ {\ "key": "2017",\ "key_display_name": "2017",\ "count": 14789\ },\ ...\ ] --- # Works | OpenAlex technical documentation Works are scholarly documents like journal articles, books, datasets, and theses. OpenAlex indexes over 240M works, with about 50,000 added daily. You can access a work in the OpenAlex API like this: * Get a list of OpenAlex works: [`https://api.openalex.org/works`](https://api.openalex.org/works) That will return a list of [`Work`](https://docs.openalex.org/api-entities/works/work-object) object, describing everything OpenAlex knows about each work. We collect new works from many sources, including Crossref, PubMed, institutional and discipline-specific repositories (eg, arXiv). Many older works come from the now-defunct Microsoft Academic Graph (MAG). Works are linked to other works via the [`referenced_works`](https://docs.openalex.org/api-entities/works/work-object#referenced_works) (outgoing citations), [`cited_by_api_url`](https://docs.openalex.org/api-entities/works/work-object#cited_by_api_url) (incoming citations), and [`related_works`](https://docs.openalex.org/api-entities/works/work-object#related_works) properties. [](https://docs.openalex.org/api-entities/works#whats-next) What's next ---------------------------------------------------------------------------- Learn more about what you can do with works: * [The Work object](https://docs.openalex.org/api-entities/works/work-object) * [Get a single work](https://docs.openalex.org/api-entities/works/get-a-single-work) * [Get lists of works](https://docs.openalex.org/api-entities/works/get-lists-of-works) * [Filter works](https://docs.openalex.org/api-entities/works/filter-works) * [Search for works](https://docs.openalex.org/api-entities/works/search-works) * [Group works](https://docs.openalex.org/api-entities/works/group-works) * [Get N-grams](https://docs.openalex.org/api-entities/works/get-n-grams) [PreviousEntities overview](https://docs.openalex.org/api-entities/entities-overview) [NextWork object](https://docs.openalex.org/api-entities/works/work-object) Last updated 22 days ago --- # Entities overview | OpenAlex technical documentation The OpenAlex dataset describes scholarly _entities_ and how those entities are connected to each other. Together, these make a huge web (or more technically, heterogeneous directed [graph](https://en.wikipedia.org/wiki/Graph_theory) ) of hundreds of millions of entities and billions of connections between them all. Learn more about the OpenAlex entities: * [Works](https://docs.openalex.org/api-entities/works) : Scholarly documents like journal articles, books, datasets, and theses * [Authors](https://docs.openalex.org/api-entities/authors) : People who create works * [Sources](https://docs.openalex.org/api-entities/sources) : Where works are hosted (such as journals, conferences, and repositories) * [Institutions](https://docs.openalex.org/api-entities/institutions) : Universities and other organizations to which authors claim affiliations * [Topics](https://docs.openalex.org/api-entities/topics) : Topics assigned to works * [Publishers](https://docs.openalex.org/api-entities/publishers) : Companies and organizations that distribute works * [Funders](https://docs.openalex.org/api-entities/funders) : Organizations that fund research * [Geo](https://docs.openalex.org/api-entities/geo) : Where things are in the world [PreviousQuickstart tutorial](https://docs.openalex.org/quickstart-tutorial) [NextWorks](https://docs.openalex.org/api-entities/works) Last updated 22 days ago --- # Get N-grams | OpenAlex technical documentation N-grams list the words and phrases that occur in the full text of a [`Work`](https://docs.openalex.org/api-entities/works/work-object) . We obtain them from Internet Archive's publicly (and generously 👏) available [General Index](https://archive.org/details/GeneralIndex) and use them to enable fulltext searches on the Works that have them, through both the [`fulltext.search`](https://docs.openalex.org/api-entities/works/filter-works#fulltext.search) _filter_, and as an element of the more holistic [`search`](https://docs.openalex.org/api-entities/works/search-works#works-full-search) _parameter_. Note that while n-grams are derived from the fulltext of a Work, the presence of n-grams for a given Work doesn't imply that the fulltext is available to you, the reader. It only means the fulltext was available to Internet Archive for indexing. [`Work.open_access`](https://docs.openalex.org/api-entities/works/work-object#open_access) is the place to go for information on public fulltext availability. [](https://docs.openalex.org/api-entities/works/get-n-grams#api-endpoint) API Endpoint ------------------------------------------------------------------------------------------- The n-gram API endpoint is not currently in service. The n-grams are still used on our backend to help power fulltext search. If you have any questions about this, please [submit a support ticket](https://openalex.org/feedback) . [](https://docs.openalex.org/api-entities/works/get-n-grams#fulltext-coverage) Fulltext Coverage ----------------------------------------------------------------------------------------------------- You can see which works we have full-text for using the [`has_fulltext`](https://docs.openalex.org/api-entities/works/work-object#has_fulltext) filter. This does not necessarily mean that the full text is available to you, dear reader; rather, it means that we have indexed the full text and can use it to help power [searches](https://github.com/ourresearch/openalex-elastic-api/blob/master/docs/api-entities/search-works.md) . If you are trying to find the full text for yourself, try looking in [`open_access.oa_url`](https://docs.openalex.org/api-entities/works#open_access) . We get access to the full text in one of two ways: either using an open-access PDF, or using [N-grams obtained from the Internet Archive](https://github.com/ourresearch/openalex-elastic-api/blob/master/docs/api-entities/get-n-grams.md) . You can learn where a work's full text came from at [`fulltext_origin`](https://docs.openalex.org/api-entities/works#fulltext_origin) . About 57 million works have n-grams coverage through [Internet Archive](https://archive.org/details/GeneralIndex) . OurResearch is the first organization to host this data in a highly usable way, and we are proud to integrate it into OpenAlex! Curious about n-grams used in search? [Browse them all](https://docs.openalex.org/api-entities/works/work-object#ngrams_url) via the API. Highly-cited works and less recent works are more likely to have n-grams, as shown by the coverage charts below: [PreviousGroup works](https://docs.openalex.org/api-entities/works/group-works) [NextAuthors](https://docs.openalex.org/api-entities/authors) Last updated 22 days ago * [API Endpoint](https://docs.openalex.org/api-entities/works/get-n-grams#api-endpoint) * [Fulltext Coverage](https://docs.openalex.org/api-entities/works/get-n-grams#fulltext-coverage) --- # Authors | OpenAlex technical documentation Authors are people who create works. You can get an author from the API like this: * Get a list of OpenAlex authors: [`https://api.openalex.org/authors`](https://api.openalex.org/authors) The [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for authors is ORCID; only a small percentage of authors have one, but the percentage is higher for more recent works. Our information about authors comes from MAG, Crossref, PubMed, ORCID, and publisher websites, among other sources. To learn more about how we combine this information to get OpenAlex Authors, see [Author Disambiguation](https://help.openalex.org/hc/en-us/articles/24347048891543-Author-disambiguation) . Authors are linked to works via the [`works.authorships`](https://docs.openalex.org/api-entities/works/work-object#authorships) property. [](https://docs.openalex.org/api-entities/authors#whats-next) What's next ------------------------------------------------------------------------------ Learn more about what you can with authors: * [The Author object](https://docs.openalex.org/api-entities/authors/author-object) * [Get a single author](https://docs.openalex.org/api-entities/authors/get-a-single-author) * [Get lists of authors](https://docs.openalex.org/api-entities/authors/get-lists-of-authors) * [Filter authors](https://docs.openalex.org/api-entities/authors/filter-authors) * [Search authors](https://docs.openalex.org/api-entities/authors/search-authors) * [Group authors](https://docs.openalex.org/api-entities/authors/group-authors) [PreviousGet N-grams](https://docs.openalex.org/api-entities/works/get-n-grams) [NextAuthor object](https://docs.openalex.org/api-entities/authors/author-object) Last updated 22 days ago --- # Get a single work | OpenAlex technical documentation It's easy to get a work from from the API with: `/works/` Here's an example: * Get the work with the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) `W2741809807`: [`https://api.openalex.org/works/W2741809807`](https://api.openalex.org/works/W2741809807) That will return a [`Work`](https://docs.openalex.org/api-entities/works/work-object) object, describing everything OpenAlex knows about the work with that ID. Copy { "id": "https://openalex.org/W2741809807", "doi": "https://doi.org/10.7717/peerj.4375", "title": "The state of OA: a large-scale analysis of the prevalence and impact of Open Access articles", "display_name": "The state of OA: a large-scale analysis of the prevalence and impact of Open Access articles", "publication_year": 2018, "publication_date": "2018-02-13", // other fields removed for brevity } You can make up to 50 of these queries at once by requesting a list of entities and filtering on IDs [using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) ([tutorial](https://blog.ourresearch.org/fetch-multiple-dois-in-one-openalex-api-request/) ). [](https://docs.openalex.org/api-entities/works/get-a-single-work#external-ids) External IDs ------------------------------------------------------------------------------------------------- You can look up works using external IDs such as a DOI: * Get the work with this DOI: `https://doi.org/10.7717/peerj.4375`: [https://api.openalex.org/works/https://doi.org/10.7717/peerj.4375](https://api.openalex.org/works/https://doi.org/10.7717/peerj.4375) You can use the full ID or a shorter Uniform Resource Name (URN) format like so: * Get the work with PubMed ID: `https://pubmed.ncbi.nlm.nih.gov/14907713`: [https://api.openalex.org/works/pmid:14907713](https://api.openalex.org/works/pmid:14907713) Available external IDs for works are: External ID URN DOI `doi` Microsoft Academic Graph (MAG) `mag` PubMed ID (PMID) `pmid` PubMed Central ID (PMCID) `pmcid` You must make sure that the ID(s) you supply are valid and correct. If an ID you request is incorrect, you will get no result. If you request an illegal ID—such as one containing a `,` or `&`, the query will fail and you will get a 403 error. ### [](https://docs.openalex.org/api-entities/works/get-a-single-work#select-fields) Select fields You can use `select` to limit the fields that are returned in a work object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` for a work object [https://api.openalex.org/works/W2741809807?select=id,display\_name](https://api.openalex.org/works/W2741809807?select=id,display_name) [PreviousLocation object](https://docs.openalex.org/api-entities/works/work-object/location-object) [NextGet lists of works](https://docs.openalex.org/api-entities/works/get-lists-of-works) Last updated 22 days ago * [External IDs](https://docs.openalex.org/api-entities/works/get-a-single-work#external-ids) * [Select fields](https://docs.openalex.org/api-entities/works/get-a-single-work#select-fields) --- # Authorship object | OpenAlex technical documentation The Authorship object represents a single author and her institutional affiliations in the context of a given work. It is only found as part of a `Work` object, in the [`work.authorships`](https://docs.openalex.org/api-entities/works/work-object#authorships) property. ### [](https://docs.openalex.org/api-entities/works/work-object/authorship-object#affiliations) `affiliations` _List:_ List of objects Each institutional affiliation that this author has claimed will be listed here: the raw affiliation string that we found, along with the OpenAlex [`Institution`](https://docs.openalex.org/api-entities/institutions) ID or IDs that we matched it to. This information will be redundant with [`institutions`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) below, but is useful if you need to know about what we used to match institutions. Copy affiliations: [\ {\ raw_affiliation_string: "Scholarly Communications Lab, Simon Fraser University, Vancouver, Canada",\ institution_ids: [\ "https://openalex.org/I18014758"\ ]\ }\ ] ### [](https://docs.openalex.org/api-entities/works/work-object/authorship-object#author) `author` _String:_ An author of this work, as a dehydrated [`Author`](https://docs.openalex.org/api-entities/authors/author-object) object. Note that, sometimes, we assign ORCID using [author disambiguation](https://github.com/ourresearch/openalex-elastic-api/blob/master/docs/api-entities/works/authors/author-disambiguation.md) , so the ORCID we associate with an author was not necessarily included with this work. Copy author: { id: "https://openalex.org/A5085171399", display_name: "Juan Pablo Alperin", orcid: "https://orcid.org/0000-0002-9344-7439" } ### [](https://docs.openalex.org/api-entities/works/work-object/authorship-object#author_position) `author_position` _String:_ A summarized description of this author's position in the work's author list. Possible values are `first`, `middle`, and `last`. It's not strictly necessary, because author order is already implicitly recorded by the list order of `Authorship` objects; however it's useful in some contexts to have this as a categorical value. ### [](https://docs.openalex.org/api-entities/works/work-object/authorship-object#countries) `countries` _List:_ The country or countries for this author. We determine the countries using a combination of matched institutions and parsing of the raw affiliation strings, so we can have this information for some authors even if we do not have a specific institutional affiliation. ### [](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) `institutions` _List:_ The institutional affiliations this author claimed in the context of this work, as [dehydrated `Institution`](https://docs.openalex.org/api-entities/institutions/institution-object#the-dehydratedinstitution-object) objects. ### [](https://docs.openalex.org/api-entities/works/work-object/authorship-object#is_corresponding) `is_corresponding` _Boolean:_ If `true`, this is a corresponding author for this work. This is a new feature, and the information may be missing for many works. We are working on this, and coverage will improve soon. ### [](https://docs.openalex.org/api-entities/works/work-object/authorship-object#raw_affiliation_strings) `raw_affiliation_strings` _List:_ This author's affiliation as it originally came to us (on a webpage or in an API), as a list of raw unformatted strings. If there is only one affiliation, it will be a list of length one. ### [](https://docs.openalex.org/api-entities/works/work-object/authorship-object#raw_author_name) `raw_author_name` _String:_ This author's name as it originally came to us (on a webpage or in an API), as a raw unformatted string. [PreviousWork object](https://docs.openalex.org/api-entities/works/work-object) [NextLocation object](https://docs.openalex.org/api-entities/works/work-object/location-object) Last updated 22 days ago * [affiliations](https://docs.openalex.org/api-entities/works/work-object/authorship-object#affiliations) * [author](https://docs.openalex.org/api-entities/works/work-object/authorship-object#author) * [author\_position](https://docs.openalex.org/api-entities/works/work-object/authorship-object#author_position) * [countries](https://docs.openalex.org/api-entities/works/work-object/authorship-object#countries) * [institutions](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) * [is\_corresponding](https://docs.openalex.org/api-entities/works/work-object/authorship-object#is_corresponding) * [raw\_affiliation\_strings](https://docs.openalex.org/api-entities/works/work-object/authorship-object#raw_affiliation_strings) * [raw\_author\_name](https://docs.openalex.org/api-entities/works/work-object/authorship-object#raw_author_name) Copy author_position: "first" Copy countries: [\ "US"\ ] Copy institutions: [\ {\ id: "https://openalex.org/I18014758",\ display_name: "Simon Fraser University",\ ror: "https://ror.org/0213rcc28",\ country_code: "CA",\ type: "education",\ lineage: ["https://openalex.org/I18014758"]\ }\ ] Copy raw_affiliation_strings: [\ "Canadian Institute for Studies in Publishing, Simon Fraser University"\ ], Copy raw_author_name: "Juan Pablo Alperin" --- # Location object | OpenAlex technical documentation The `Location` object describes the location of a given work. It's only found as part of the `Work` object. Locations are meant to capture the way that a work exists in different versions. So, for example, a work may have a version that has been peer-reviewed and published in a journal (the [version of record](https://en.wikipedia.org/wiki/Version_of_record) ). This would be one of the work's locations. It may have another version available on a preprint server like [bioRxiv](https://www.biorxiv.org/) —this version having been posted before it was accepted for publication. This would be another one of the work's locations. Below is an example of a work in OpenAlex ([https://openalex.org/W2807749226](https://openalex.org/W2807749226) ) that has multiple locations with different properties. The version of record, published in a peer-reviewed journal, is listed first, and is not open-access. The second location is a university repository, where one can find an open-access copy of the published version of the work. Other locations are listed below. Locations are meant to cover anywhere that a given work can be found. This can include journals, proceedings, institutional repositories, and subject-area repositories like [arXiv](https://arxiv.org/) and [bioRxiv](https://www.biorxiv.org/) . If you are only interested in a certain one of these (like journal), you can use a [filter](https://docs.openalex.org/api-entities/works/filter-works) to specify the `locations.source.type`. ([Learn more about types here.](https://docs.openalex.org/api-entities/sources/source-object#type) ) There are three places in the `Work` object where you can find locations: * [`primary_location`](https://docs.openalex.org/api-entities/works/work-object#primary_location) : The best (closest to the [version of record](https://en.wikipedia.org/wiki/Version_of_record) ) copy of this work. * [`best_oa_location`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) : The best available open access location of this work. * [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) : A list of all of the locations where this work lives. This will include the two locations above if availabe, and can also include other locations. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#id) `id` _String:_ A unique identifier for this location. The format is `prefix:identifier`, where the prefix indicates the provenance of the location: * `doi:` — from Crossref or DataCite * `pmid:` — from PubMed * `mag:` — from Microsoft Academic Graph * `pmh:` — from OAI-PMH repository harvesting This identifier is globally unique across all locations. Copy id: "doi:10.1590/s1678-77572010000100010" ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#is_accepted) `is_accepted` _Boolean:_ `true` if this location's [`version`](https://docs.openalex.org/api-entities/works/work-object/location-object#version) is either `acceptedVersion` or `publishedVersion`; otherwise `false`. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#is_oa) `is_oa` _Boolean:_ `True` if an Open Access (OA) version of this work is available at this location. There are [many ways to define OA](https://peerj.com/articles/4375/#literature-review) . OpenAlex uses a broad definition: having a URL where you can read the fulltext of this work without needing to pay money or log in. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#is_published) `is_published` _Boolean:_ `true` if this location's [`version`](https://docs.openalex.org/api-entities/works/work-object/location-object#version) is `publishedVersion`; otherwise `false`. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#landing_page_url) landing\_page\_url _String:_ The landing page URL for this location. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#license) license _String:_ The location's publishing license. This can be a [Creative Commons](https://creativecommons.org/about/cclicenses/) license such as cc0 or cc-by, a publisher-specific license, or null which means we are not able to determine a license for this location. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#license_id) `license_id` _String:_ The OpenAlex ID for this license, if available. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#source) source _Object:_ Information about the source of this location, as a [`DehydratedSource`](https://docs.openalex.org/api-entities/sources/source-object#the-dehydratedsource-object) object. The concept of a source is meant to capture a certain social relationship between the host organization and a version of a work. When an organization puts the work on the internet, there is an understanding that they have, at some level, endorsed the work. This level varies, and can be very different depending on the source! The source object includes these additional fields: * `is_oa`: _Boolean_ — whether this source is fully open access * `is_in_doaj`: _Boolean_ — whether this source is indexed in the [Directory of Open Access Journals](https://doaj.org/) * `is_core`: _Boolean_ — whether this source is indexed in [CORE](https://core.ac.uk/) * `host_organization_name`: _String_ — the name of the host organization * `host_organization_lineage`: _List_ — OpenAlex IDs of the host organization's parent organizations * `host_organization_lineage_names`: _List_ — names of the host organization's parent organizations ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#pdf_url) pdf\_url _String:_ A URL where you can find this location as a PDF. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#version) version _String:_ The version of the work, based on the [DRIVER Guidelines versioning scheme.](https://wiki.surfnet.nl/display/DRIVERguidelines/DRIVER-VERSION+Mappings) Possible values are:. * `publishedVersion`: The document’s version of record. This is the most authoritative version. * `acceptedVersion`: The document after having completed peer review and being officially accepted for publication. It will lack publisher formatting, but the _content_ should be interchangeable with the that of the `publishedVersion`. * `submittedVersion`: the document as submitted to the publisher by the authors, but _before_ peer-review. Its content may differ significantly from that of the accepted article. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#raw_source_name) `raw_source_name` _String:_ The name of the source as it originally appeared in the metadata, before normalization. ### [](https://docs.openalex.org/api-entities/works/work-object/location-object#raw_type) raw\_type _String:_ The type, _according to this location's source_. This uses whatever controlled vocabulary that source happens to fancy. So for example: if the location is from from Crossref, you'll see a term from [the Crossref type vocabulary](https://api.crossref.org/types) in the `location.raw_type` field. [PreviousAuthorship object](https://docs.openalex.org/api-entities/works/work-object/authorship-object) [NextGet a single work](https://docs.openalex.org/api-entities/works/get-a-single-work) Last updated 22 days ago * [id](https://docs.openalex.org/api-entities/works/work-object/location-object#id) * [is\_accepted](https://docs.openalex.org/api-entities/works/work-object/location-object#is_accepted) * [is\_oa](https://docs.openalex.org/api-entities/works/work-object/location-object#is_oa) * [is\_published](https://docs.openalex.org/api-entities/works/work-object/location-object#is_published) * [landing\_page\_url](https://docs.openalex.org/api-entities/works/work-object/location-object#landing_page_url) * [license](https://docs.openalex.org/api-entities/works/work-object/location-object#license) * [license\_id](https://docs.openalex.org/api-entities/works/work-object/location-object#license_id) * [source](https://docs.openalex.org/api-entities/works/work-object/location-object#source) * [pdf\_url](https://docs.openalex.org/api-entities/works/work-object/location-object#pdf_url) * [version](https://docs.openalex.org/api-entities/works/work-object/location-object#version) * [raw\_source\_name](https://docs.openalex.org/api-entities/works/work-object/location-object#raw_source_name) * [raw\_type](https://docs.openalex.org/api-entities/works/work-object/location-object#raw_type) Copy is_accepted: true Copy is_oa: true Copy is_published: true Copy landing_page_url: "https://doi.org/10.1590/s1678-77572010000100010" Copy license: "cc-by" Copy license_id: "https://openalex.org/licenses/cc-by" Copy source: { id: "https://openalex.org/S125754415", display_name: "Proceedings of the National Academy of Sciences of the United States of America", issn_l: "0027-8424", issn: ["1091-6490", "0027-8424"], is_oa: false, is_in_doaj: false, is_core: true, host_organization: "https://openalex.org/P4310320052", host_organization_name: "National Academy of Sciences", host_organization_lineage: ["https://openalex.org/P4310320052"], host_organization_lineage_names: ["National Academy of Sciences"], type: "journal" } Copy pdf_url: "http://www.scielo.br/pdf/jaos/v18n1/a10v18n1.pdf" Copy version: "publishedVersion" Copy raw_source_name: "Journal of Applied Oral Science" Copy raw_type: "journal-article" --- # Search works | OpenAlex technical documentation The best way to search for works is to use the `search` query parameter, which searches across [titles](https://docs.openalex.org/api-entities/works/work-object#title) , [abstracts](https://docs.openalex.org/api-entities/works/work-object#abstract_inverted_index) , and [fulltext](https://docs.openalex.org/api-entities/works/work-object#has_fulltext) . Example: * Get works with search term "dna" in the title, abstract, or fulltext: [`https://api.openalex.org/works?search=dna`](https://api.openalex.org/works?search=dna) Fulltext search is available for a subset of works, see [`Work.has_fulltext`](https://docs.openalex.org/api-entities/works/work-object#has_fulltext) for more details. You can read more about search [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. [](https://docs.openalex.org/api-entities/works/search-works#search-a-specific-field) Search a specific field ------------------------------------------------------------------------------------------------------------------ You can use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , allowing you to fine-tune the fields you're searching over. To do this, you append `.search` to the end of the property you are filtering for: * Get works with "cubist" in the title: [`https://api.openalex.org/works?filter=title.search:cubist`](https://api.openalex.org/works?filter=title.search:cubist) The following fields can be searched within works: Search filter Field that is searched [`abstract.search`](https://docs.openalex.org/api-entities/works/filter-works#abstract.search) [`abstract_inverted_index`](https://docs.openalex.org/api-entities/works/work-object#abstract_inverted_index) [`display_name.search`](https://docs.openalex.org/api-entities/works/filter-works#display_name.search-alias-title.search) [`display_name`](https://docs.openalex.org/api-entities/works/work-object#display_name) [`fulltext.search`](https://docs.openalex.org/api-entities/works/filter-works#fulltext.search) fulltext via [`n-grams`](https://docs.openalex.org/api-entities/works/get-n-grams) [`raw_affiliation_strings.search`](https://docs.openalex.org/api-entities/works/filter-works#raw_affiliation_stringssearch) [`authorships.raw_affiliation_strings`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#raw_affiliation_strings) [`title.search`](https://docs.openalex.org/api-entities/works/filter-works#display_name.search-alias-title.search) [`display_name`](https://docs.openalex.org/api-entities/works/work-object#display_name) [`title_and_abstract.search`](https://docs.openalex.org/api-entities/works/filter-works#title_and_abstractsearch) [`display_name`](https://docs.openalex.org/api-entities/works/work-object#display_name) and [`abstract_inverted_index`](https://docs.openalex.org/api-entities/works/work-object#abstract_inverted_index) You can also use the filter `default.search`, which works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/works/search-works#search-works) . These searches make use of stemming and stop-word removal. You can disable this for searches on titles and abstracts. Learn how to do this [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#search-without-stemming) . ### [](https://docs.openalex.org/api-entities/works/search-works#why-cant-i-search-by-name-of-related-entity-author-name-institution-name-etc) Why can't I search by name of related entity (author name, institution name, etc.)? Rather than searching for the _names_ of entities related to works—such as authors, institutions, and sources—you need to search by a more unique identifier for that entity, like the OpenAlex ID. This means that there is a 2 step process: 1. Find the ID of the related entity. For example, if you're interested in works associated with NYU, you could search the `/institutions` endpoint for that name: [`https://api.openalex.org/institutions?search=nyu`](https://api.openalex.org/institutions?search=nyu) . Looking at the first result, you'll see that the OpenAlex ID for NYU is `I57206974`. 2. Use a [filter](https://docs.openalex.org/api-entities/works/filter-works) with the `/works` endpoint to get all of the works: [`https://api.openalex.org/works?filter=institutions.id:I57206974`](https://api.openalex.org/works?filter=institutions.id:I57206974) . Why can't you do this in just one step? Well, if you use the search term, "NYU," you might end up missing the ones that use the full name "New York University," rather than the initials. Sure, you could try to think of all possible variants and search for all of them, but you might miss some, and you risk putting in search terms that let in works that you're not interested in. Figuring out which works are actually associated with the "NYU" you're interested shouldn't be your responsibility—that's our job! We've done that work for you, so all the relevant works should be associated with one unique ID. [](https://docs.openalex.org/api-entities/works/search-works#autocomplete-works) Autocomplete works -------------------------------------------------------------------------------------------------------- You can autocomplete works to create a very fast type-ahead style search function: * Autocomplete works with "tigers" in the title: [`https://api.openalex.org/autocomplete/works?q=tigers`](https://api.openalex.org/autocomplete/works?q=tigers) This returns a list of works titles with the author of each work set as the hint: Read more about [autocomplete](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) . [PreviousFilter works](https://docs.openalex.org/api-entities/works/filter-works) [NextGroup works](https://docs.openalex.org/api-entities/works/group-works) Last updated 22 days ago * [Search a specific field](https://docs.openalex.org/api-entities/works/search-works#search-a-specific-field) * [Why can't I search by name of related entity (author name, institution name, etc.)?](https://docs.openalex.org/api-entities/works/search-works#why-cant-i-search-by-name-of-related-entity-author-name-institution-name-etc) * [Autocomplete works](https://docs.openalex.org/api-entities/works/search-works#autocomplete-works) Copy { "results": [\ {\ "id": "https://openalex.org/W2125098916",\ "display_name": "Crouching tigers, hidden prey: Sumatran tiger and prey populations in a tropical forest landscape",\ "hint": "Timothy G. O'Brien, Margaret F. Kinnaird, Hariyo T. Wibisono",\ "cited_by_count": 620,\ "works_count": null,\ "entity_type": "work",\ "external_id": "https://doi.org/10.1017/s1367943003003172"\ },\ ...\ ] } --- # Author disambiguation | OpenAlex technical documentation We have created a page in our help docs to give you all the information you need about our author disambiguation including information about author IDs, how we disambiguate authors, and how you can curate your author profile. Go to [this page](https://help.openalex.org/hc/en-us/articles/24347048891543-Author-disambiguation) to find out what you need to know! [PreviousLimitations](https://docs.openalex.org/api-entities/authors/limitations) [NextSources](https://docs.openalex.org/api-entities/sources) Last updated 22 days ago --- # Sources | OpenAlex technical documentation Sources are where works are hosted. OpenAlex indexes about 249,000 sources. There are several types, including journals, conferences, preprint repositories, and institutional repositories. * Get a list of OpenAlex sources: [`https://api.openalex.org/sources`](https://api.openalex.org/sources) The [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for sources is ISSN-L, which is a special "main" ISSN assigned to every sources (sources tend to have multiple ISSNs). About 90% of sources in OpenAlex have an ISSN-L or ISSN. Our information about sources comes from Crossref, the ISSN Network, and MAG. These datasets are joined automatically where possible, but there’s also a lot of manual combining involved. We do not curate journals, so any journal that is available in the data sources should make its way into OpenAlex. Several sources may host the same work. OpenAlex reports both the primary host source (generally wherever the [version of record](https://en.wikipedia.org/wiki/Version_of_record) lives), and alternate host sources (like preprint repositories). Sources are linked to works via the [`works.primary_location`](https://docs.openalex.org/api-entities/works/work-object#primary_location) and [`works.locations`](https://docs.openalex.org/api-entities/works/work-object#locations) properties. Check out the [Japanese Sources tutorial](https://github.com/ourresearch/openalex-api-tutorials/blob/main/notebooks/institutions/japan_sources.ipynb) , a Jupyter notebook showing how to use Python and the API to learn about all of the sources in a country. [](https://docs.openalex.org/api-entities/sources#whats-next) What's next ------------------------------------------------------------------------------ Learn more about what you can do with sources: * [The Source object](https://docs.openalex.org/api-entities/sources/source-object) * [Get a single source](https://docs.openalex.org/api-entities/sources/get-a-single-source) * [Get lists of sources](https://docs.openalex.org/api-entities/sources/get-lists-of-sources) * [Filter sources](https://docs.openalex.org/api-entities/sources/filter-sources) * [Search sources](https://docs.openalex.org/api-entities/sources/search-sources) * [Group sources](https://docs.openalex.org/api-entities/sources/group-sources) [PreviousAuthor disambiguation](https://docs.openalex.org/api-entities/authors/author-disambiguation) [NextSource object](https://docs.openalex.org/api-entities/sources/source-object) Last updated 22 days ago --- # Limitations | OpenAlex technical documentation [](https://docs.openalex.org/api-entities/authors/limitations#works-with-more-than-100-authors-are-truncated) Works with more than 100 authors are truncated ----------------------------------------------------------------------------------------------------------------------------------------------------------------- When retrieving a list of works in the API, the `authorships` list within each work will be cut off at 100 authorships objects in order to keep things running well. When this happens the boolean value `is_authors_truncated` will be available and set to `true`. This affects a small portion of OpenAlex, as there are around 35,000 works with more than 100 authors. This limitation does not apply to the [data snapshot](https://docs.openalex.org/download-all-data/openalex-snapshot) . * Example list of works with truncated authors [`https://api.openalex.org/works?filter=authors\_count:>100`](https://api.openalex.org/works?filter=authors_count:%3E100) To see the full list of authors, go to the individual record for the work, which is never truncated. * Work with all 249 authors available [`https://api.openalex.org/works/W2168909179`](https://api.openalex.org/works/W2168909179) This affects filtering as well. So if you filter works using an author ID or ROR, you will not receive works where that author is listed further than 100 places down on the list of authors. We plan to change this in the future, so that filtering works as expected. [PreviousGroup authors](https://docs.openalex.org/api-entities/authors/group-authors) [NextAuthor disambiguation](https://docs.openalex.org/api-entities/authors/author-disambiguation) Last updated 22 days ago --- # Get lists of works | OpenAlex technical documentation You can get lists of works: * Get _all_ of the works in OpenAlex [`https://api.openalex.org/works`](https://api.openalex.org/works) Which returns a response like this: Copy { "meta": { "count": 245684392, "db_response_time_ms": 929, "page": 1, "per_page": 25 }, "results": [\ {\ "id": "https://openalex.org/W1775749144",\ "doi": "https://doi.org/10.1016/s0021-9258(19)52451-6",\ "title": "PROTEIN MEASUREMENT WITH THE FOLIN PHENOL REAGENT",\ // more fields (removed to save space)\ },\ {\ "id": "https://openalex.org/W2100837269",\ "doi": "https://doi.org/10.1038/227680a0",\ "title": "Cleavage of Structural Proteins during the Assembly of the Head of Bacteriophage T4",\ // more fields (removed to save space)\ },\ // more results (removed to save space)\ ], "group_by": [] } [](https://docs.openalex.org/api-entities/works/get-lists-of-works#page-and-sort-works) Page and sort works ---------------------------------------------------------------------------------------------------------------- You can [page through](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) works and change the default number of results returned with the `page` and `per-page` parameters: * Get a second page of results with 50 results per page [`https://api.openalex.org/works?per-page=50\&page=2`](https://api.openalex.org/works?per-page=50&page=2) You can [sort results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) with the `sort` parameter: * Sort works by publication year [`https://api.openalex.org/works?sort=publication\_year`](https://api.openalex.org/works?sort=publication_year) Continue on to learn how you can [filter](https://docs.openalex.org/api-entities/works/filter-works) and [search](https://docs.openalex.org/api-entities/works/search-works) lists of works. [](https://docs.openalex.org/api-entities/works/get-lists-of-works#sample-works) Sample works -------------------------------------------------------------------------------------------------- You can use `sample` to get a random batch of works. Read more about sampling and how to add a `seed` value [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) . * Get 20 random works [`https://api.openalex.org/works?sample=20`](https://api.openalex.org/works?sample=20) [](https://docs.openalex.org/api-entities/works/get-lists-of-works#select-fields) Select fields ---------------------------------------------------------------------------------------------------- You can use `select` to limit the fields that are returned in a list of works. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` within works results [`https://api.openalex.org/works?select=id,display\_name`](https://api.openalex.org/works?select=id,display_name) [PreviousGet a single work](https://docs.openalex.org/api-entities/works/get-a-single-work) [NextFilter works](https://docs.openalex.org/api-entities/works/filter-works) Last updated 22 days ago * [Page and sort works](https://docs.openalex.org/api-entities/works/get-lists-of-works#page-and-sort-works) * [Sample works](https://docs.openalex.org/api-entities/works/get-lists-of-works#sample-works) * [Select fields](https://docs.openalex.org/api-entities/works/get-lists-of-works#select-fields) --- # Group authors | OpenAlex technical documentation You can group authors with the `group_by` parameter: * Get counts of authors by the last known institution continent: [`https://api.openalex.org/authors?group_by=last_known_institution.continent`](https://api.openalex.org/authors?group_by=last_known_institution.continent) \`\` Or you can group using one the attributes below. {% hint style="info" %} It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. {% endhint %} ### [](https://docs.openalex.org/api-entities/authors/group-authors#authors-group_by-attributes) `/authors` group\_by attributes * [`affiliations.institution.country_code`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`affiliations.institution.id`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`affiliations.institution.lineage`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`affiliations.institution.ror`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`affiliations.institution.type`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`cited_by_count`](https://docs.openalex.org/api-entities/authors/author-object#cited_by_count) * [`has_orcid`](https://docs.openalex.org/api-entities/authors/filter-authors#has_orcid) * [`last_known_institution.continent`](https://docs.openalex.org/api-entities/authors/filter-authors#last_known_institution.continent) * [`last_known_institution.country_code`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`last_known_institution.id`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`last_known_institution.is_global_south`](https://docs.openalex.org/api-entities/authors/filter-authors#last_known_institution.is_global_south) * [`last_known_institution.lineage`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`last_known_institution.ror`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`last_known_institution.type`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/authors/author-object#summary_stats) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/authors/author-object#summary_stats) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/authors/author-object#summary_stats) * [`works_count`](https://docs.openalex.org/api-entities/authors/author-object#works_count) [PreviousSearch authors](https://docs.openalex.org/api-entities/authors/search-authors) [NextLimitations](https://docs.openalex.org/api-entities/authors/limitations) Last updated 22 days ago --- # Get a single author | OpenAlex technical documentation It's easy to get an author from from the API with: `/authors/`. Here's an example: * Get the author with the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) `A5023888391`: [`https://api.openalex.org/authors/A5023888391`](https://api.openalex.org/authors/A5023888391) That will return an [`Author`](https://docs.openalex.org/api-entities/authors/author-object) object, describing everything OpenAlex knows about the author with that ID: Copy { "id": "https://openalex.org/A5023888391", "orcid": "https://orcid.org/0000-0001-6187-6610", "display_name": "Jason Priem", "display_name_alternatives": [], "works_count": 53, // other fields removed for brevity } You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . Authors are also available via an alias: `/people` [](https://docs.openalex.org/api-entities/authors/get-a-single-author#external-ids) External IDs ----------------------------------------------------------------------------------------------------- You can look up authors using external IDs such as an ORCID: * Get the author with this ORCID: `https://orcid.org/0000-0002-1298-3089`: [`https://api.openalex.org/authors/https://orcid.org/0000-0002-1298-3089`](https://api.openalex.org/authors/https://orcid.org/0000-0002-1298-3089) You can use the full ID or a shorter Uniform Resource Name (URN) format like so: [`https://api.openalex.org/authors/orcid:0000-0002-1298-3089`](https://api.openalex.org/authors/orcid:0000-0002-1298-3089) Available external IDs for authors are: External ID URN ORCID `orcid` Scopus `scopus` Twitter `twitter` Wikipedia `wikipedia` [](https://docs.openalex.org/api-entities/authors/get-a-single-author#select-fields) Select fields ------------------------------------------------------------------------------------------------------- You can use `select` to limit the fields that are returned in an author object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` and orcid for an author object [`https://api.openalex.org/authors/A5023888391?select=id,display_name,orcid`](https://api.openalex.org/authors/A5023888391?select=id,display_name,orcid) [PreviousAuthor object](https://docs.openalex.org/api-entities/authors/author-object) [NextGet lists of authors](https://docs.openalex.org/api-entities/authors/get-lists-of-authors) Last updated 22 days ago * [External IDs](https://docs.openalex.org/api-entities/authors/get-a-single-author#external-ids) * [Select fields](https://docs.openalex.org/api-entities/authors/get-a-single-author#select-fields) --- # Group works | OpenAlex technical documentation You can group works with the `group_by` parameter: * Get counts of works by Open Access status: [`https://api.openalex.org/works?group_by=oa_status`](https://api.openalex.org/works?group_by=oa_status) Or you can group using one the attributes below. It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. ### [](https://docs.openalex.org/api-entities/works/group-works#works-group_by-attributes) `/works` group\_by attributes The `host_venue` and `alternate_host_venues` properties have been deprecated in favor of [`primary_location`](https://docs.openalex.org/api-entities/works/work-object#primary_location) and [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) . The attributes `host_venue` and `alternate_host_venues` are no longer available in the Work object, and trying to access them in filters or group-bys will return an error. * [`authors_count`](https://docs.openalex.org/api-entities/works/filter-works#authors_count) * [`authorships.affiliations.institution_ids`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#affiliations) * [`authorships.author.id`](https://docs.openalex.org/api-entities/works/work-object#author) (alias `author.id`) * [`authorships.author.orcid`](https://docs.openalex.org/api-entities/works/work-object#author) (alias `author.orcid`) * [`authorships.countries`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#countries) * [`authorships.institutions.country_code`](https://docs.openalex.org/api-entities/works/work-object#institutions) (alias `institutions.country_code`) * [`authorships.institutions.continent`](https://docs.openalex.org/api-entities/works/filter-works#authorships.institutions.continent-alias-institutions.continent) (alias `institutions.continent`) * [`authorships.institutions.is_global_south`](https://docs.openalex.org/api-entities/works/filter-works#authorships.institutions.is_global_south-alias-institutions.is_global_south) * [`authorships.institutions.id`](https://docs.openalex.org/api-entities/works/work-object#institutions) (alias `institutions.id`) * [`authorships.institutions.lineage`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) * [`authorships.institutions.ror`](https://docs.openalex.org/api-entities/works/work-object#institutions) (alias `institutions.ror`) * [`authorships.institutions.type`](https://docs.openalex.org/api-entities/works/work-object#institutions) (alias `institutions.type`) * [`authorships.is_corresponding`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#is_corresponding) (alias: `is_corresponding`): this marks whether or not we have corresponding author information for a given work * [`apc_list.value`](https://docs.openalex.org/api-entities/works/work-object#apc_list) * [`apc_list.currency`](https://docs.openalex.org/api-entities/works/work-object#apc_list) * [`apc_list.provenance`](https://docs.openalex.org/api-entities/works/work-object#apc_list) * [`apc_list.value_usd`](https://docs.openalex.org/api-entities/works/work-object#apc_list) * [`apc_paid.value`](https://docs.openalex.org/api-entities/works/work-object#apc_paid) * [`apc_paid.currency`](https://docs.openalex.org/api-entities/works/work-object#apc_paid) * [`apc_paid.provenance`](https://docs.openalex.org/api-entities/works/work-object#apc_paid) * [`apc_paid.value_usd`](https://docs.openalex.org/api-entities/works/work-object#apc_paid) * [`best_oa_location.is_accepted`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.is_published`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.license`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.source.host_organization`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.source.id`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.source.is_in_doaj`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.source.issn`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.source.type`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.version`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_open_version`](https://docs.openalex.org/api-entities/works/filter-works#best_open_version) * [`biblio.first_page`](https://docs.openalex.org/api-entities/works/work-object#biblio) * [`biblio.issue`](https://docs.openalex.org/api-entities/works/work-object#biblio) * [`biblio.last_page`](https://docs.openalex.org/api-entities/works/work-object#biblio) * [`biblio.volume`](https://docs.openalex.org/api-entities/works/work-object#biblio) * [`cited_by_count`](https://docs.openalex.org/api-entities/works/work-object#cited_by_count) * [`cites`](https://docs.openalex.org/api-entities/works/filter-works#cites) * [`concepts_count`](https://docs.openalex.org/api-entities/works/filter-works#concepts_count) * [`concepts.id`](https://docs.openalex.org/api-entities/works/work-object#concepts) * [`concepts.wikidata`](https://docs.openalex.org/api-entities/works/work-object#concepts) * [`corresponding_author_ids`](https://docs.openalex.org/api-entities/works/work-object#corresponding_author_ids) * [`corresponding_institution_ids`](https://docs.openalex.org/api-entities/works/work-object#corresponding_institution_ids) * [`countries_distinct_count`](https://docs.openalex.org/api-entities/works/work-object#countries_distinct_count) * [`fulltext_origin`](https://docs.openalex.org/api-entities/works/work-object#fulltext_origin) * [`grants.award_id`](https://docs.openalex.org/api-entities/works/work-object#grants) * [`grants.funder`](https://docs.openalex.org/api-entities/works/work-object#grants) * [`has_abstract`](https://docs.openalex.org/api-entities/works/filter-works#has_abstract) * [`has_doi`](https://docs.openalex.org/api-entities/works/filter-works#has_doi) * [`has_fulltext`](https://docs.openalex.org/api-entities/works/work-object#has_fulltext) * [`has_orcid`](https://docs.openalex.org/api-entities/works/filter-works#has_orcid) * [`has_pmid`](https://docs.openalex.org/api-entities/works/filter-works#has_pmid) * [`has_pmcid`](https://docs.openalex.org/api-entities/works/filter-works#has_pmcid) * [`has_ngrams`](https://docs.openalex.org/api-entities/works/filter-works#has_ngrams) (DEPRECATED) * [`has_references`](https://docs.openalex.org/api-entities/works/filter-works#has_references) * [`indexed_in`](https://docs.openalex.org/api-entities/works/work-object#indexed_in) * [`is_retracted`](https://docs.openalex.org/api-entities/works/work-object#is_retracted) * [`is_paratext`](https://docs.openalex.org/api-entities/works/work-object#is_paratext) * [`journal`](https://docs.openalex.org/api-entities/works/filter-works#journal) * [`keywords.keyword`](https://docs.openalex.org/api-entities/works/work-object#keywords) * [`language`](https://docs.openalex.org/api-entities/works/work-object#language) * [`locations.is_accepted`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.is_published`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.source.host_institutions_lineage`](https://docs.openalex.org/api-entities/works/filter-works#locations.source.host_institution_lineage) * [`locations.source.is_core`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.source.is_in_doaj`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.source.publisher_lineage`](https://docs.openalex.org/api-entities/works/filter-works#locations.source.publisher_lineage) * [`locations_count`](https://docs.openalex.org/api-entities/works/work-object#locations_count) * [`mag_only`](https://docs.openalex.org/api-entities/works/filter-works#mag_only) * [`open_access.any_repository_has_fulltext`](https://docs.openalex.org/api-entities/works/work-object#open_access) * [`open_access.is_oa`](https://docs.openalex.org/api-entities/works/work-object#is_oa-1) (alias `is_oa`) * [`open_access.oa_status`](https://docs.openalex.org/api-entities/works/work-object#oa_status) (alias `oa_status`) * [`primary_location.is_accepted`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.is_oa`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.is_published`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.license`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.has_issn`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.host_organization`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.id`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.is_core`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.is_in_doaj`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.issn`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.publisher_lineage`](https://docs.openalex.org/api-entities/works/filter-works#primary_location.source.publisher_lineage) * [`primary_location.source.type`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.version`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_topic.id`](https://docs.openalex.org/api-entities/works/work-object#primary_topic) * [`primary_topic.domain.id`](https://docs.openalex.org/api-entities/works/work-object#primary_topic) * [`primary_topic.field.id`](https://docs.openalex.org/api-entities/works/work-object#primary_topic) * [`primary_topic.subfield.id`](https://docs.openalex.org/api-entities/works/work-object#primary_topic) * [`publication_year`](https://docs.openalex.org/api-entities/works/work-object#publication_year) * [`repository`](https://docs.openalex.org/api-entities/works/filter-works#repository) * [`sustainable_development_goals.id`](https://docs.openalex.org/api-entities/works/work-object#sustainable_development_goals) * [`topics.id`](https://docs.openalex.org/api-entities/works/work-object#topics) * [`topics.domain.id`](https://docs.openalex.org/api-entities/works/work-object#topics) * [`topics.field.id`](https://docs.openalex.org/api-entities/works/work-object#topics) * [`topics.subfield.id`](https://docs.openalex.org/api-entities/works/work-object#topics) * [`type`](https://docs.openalex.org/api-entities/works/work-object#type) * [`type_crossref`](https://docs.openalex.org/api-entities/works/work-object#type_crossref) [PreviousSearch works](https://docs.openalex.org/api-entities/works/search-works) [NextGet N-grams](https://docs.openalex.org/api-entities/works/get-n-grams) Last updated 22 days ago --- # Filter sources | OpenAlex technical documentation You can filter sources with the `filter` parameter: * Get sources that have an ISSN [`https://api.openalex.org/sources?filter=has_issn:true`](https://api.openalex.org/sources?filter=has_issn:true) It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query ### [](https://docs.openalex.org/api-entities/sources/filter-sources#sources-attribute-filters) `/sources` attribute filters You can filter using these attributes of the `Source` entity object (click each one to view their documentation on the [`Source`](https://docs.openalex.org/api-entities/sources/source-object) object page): * [`apc_prices.currency`](https://docs.openalex.org/api-entities/sources/source-object#apc_prices) * [`apc_prices.price`](https://docs.openalex.org/api-entities/sources/source-object#apc_prices) * [`apc_usd`](https://docs.openalex.org/api-entities/sources/source-object#apc_usd) * [`cited_by_count`](https://docs.openalex.org/api-entities/sources/source-object#cited_by_count) * [`country_code`](https://docs.openalex.org/api-entities/sources/source-object#country_code) * [`host_organization`](https://docs.openalex.org/api-entities/sources/source-object#host_organization) (alias: `host_organization.id`) * [`host_organization_lineage`](https://docs.openalex.org/api-entities/sources/source-object#host_organization_lineage) — Use this with a publisher ID to find works from that publisher and all of its children. * [`ids.openalex`](https://docs.openalex.org/api-entities/sources/source-object#ids) (alias: `openalex`) * [`is_core`](https://docs.openalex.org/api-entities/sources/source-object#is_core) * [`is_in_doaj`](https://docs.openalex.org/api-entities/sources/source-object#is_in_doaj) * [`is_oa`](https://docs.openalex.org/api-entities/sources/source-object#is_oa) * [`issn`](https://docs.openalex.org/api-entities/sources/source-object#issn) * [`publisher`](https://docs.openalex.org/api-entities/sources/source-object#publisher) — Requires exact match. Use the [`host_organization_lineage`](https://docs.openalex.org/api-entities/sources/source-object#host_organization_lineage) filter instead if you want to find works from a publisher and all of its children. * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/sources/source-object#summary_stats) (accepts float, null, !null, can use range queries such as < >) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/sources/source-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/sources/source-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`type`](https://docs.openalex.org/api-entities/sources/source-object#type) * [`works_count`](https://docs.openalex.org/api-entities/sources/source-object#works_count) * [`x_concepts.id`](https://docs.openalex.org/api-entities/sources/source-object#x_concepts) (alias: `concepts.id` or `concept.id`) -- will be deprecated soon Want to filter by `host_organization.display_name`? This is a two-step process: 1. Find the host organization's ID by searching by `display_name` in Publishers or Institutions, depending on which type you are looking for. 2. Filter works by `host_organization.id`. To learn more about why we do it this way, [see here.](https://docs.openalex.org/api-entities/works/search-works#why-cant-i-search-by-name-of-related-entity-author-name-institution-name-etc.) ### [](https://docs.openalex.org/api-entities/sources/filter-sources#sources-convenience-filters) `/sources` convenience filters These filters aren't attributes of the [`Source`](https://docs.openalex.org/api-entities/sources/source-object) object, but they're included to address some common use cases: #### [](https://docs.openalex.org/api-entities/sources/filter-sources#continent) `continent` Value: a String with a valid [continent filter](https://docs.openalex.org/api-entities/geo/continents#filter-by-continent) Returns: sources that are associated with the chosen continent. * Get sources that are associated with Asia [`https://api.openalex.org/sources?filter=continent:asia`](https://api.openalex.org/sources?filter=continent:asia) #### [](https://docs.openalex.org/api-entities/sources/filter-sources#default.search) `default.search` Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/sources/search-sources#search-sources) for Sources. #### [](https://docs.openalex.org/api-entities/sources/filter-sources#display_name.search) `display_name.search` Value: a search string Returns: sources with a [`display_name`](https://docs.openalex.org/api-entities/sources/source-object#display_name) containing the given string; see the [search page](https://docs.openalex.org/api-entities/sources/search-sources) for details. * Get sources with names containing "Neurology": [`https://api.openalex.org/sources?filter=display_name.search:Neurology`](https://api.openalex.org/sources?filter=display_name.search:Neurology) \`\` {% hint style="info" %} In most cases, you should use the [`search`](https://docs.openalex.org/api-entities/sources/search-sources#sources-full-search) parameter instead of this filter because it uses a better search algorithm. {% endhint %} #### [](https://docs.openalex.org/api-entities/sources/filter-sources#has_issn) `has_issn` Value: a Boolean (`true` or `false`) Returns: sources that have or lack an [ISSN](https://docs.openalex.org/api-entities/sources/source-object#issn) , depending on the given value. * Get sources without ISSNs: [`https://api.openalex.org/sources?filter=has_issn:false`](https://api.openalex.org/sources?filter=has_issn:false) \`\` #### [](https://docs.openalex.org/api-entities/sources/filter-sources#is_global_south) `is_global_south` Value: a Boolean (`true` or `false`) Returns: sources that are associated with the [Global South](https://docs.openalex.org/api-entities/geo/regions#global-south) . * Get sources that are located in the Global South [`https://api.openalex.org/sources?filter=is\_global\_south:true`](https://api.openalex.org/sources?filter=is_global_south:true) [PreviousGet lists of sources](https://docs.openalex.org/api-entities/sources/get-lists-of-sources) [NextSearch sources](https://docs.openalex.org/api-entities/sources/search-sources) Last updated 22 days ago * [/sources attribute filters](https://docs.openalex.org/api-entities/sources/filter-sources#sources-attribute-filters) * [/sources convenience filters](https://docs.openalex.org/api-entities/sources/filter-sources#sources-convenience-filters) --- # Group sources | OpenAlex technical documentation You can group sources with the `group_by` parameter: * Get counts of sources by publisher: [https://api.openalex.org/sources?group\_by=publisher](https://api.openalex.org/sources?group_by=publisher) Or you can group using one the attributes below. It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. ### [](https://docs.openalex.org/api-entities/sources/group-sources#sources-group_by-attributes) `/sources` group\_by attributes * [`apc_prices.currency`](https://docs.openalex.org/api-entities/sources/source-object#apc_prices) * [`apc_usd`](https://docs.openalex.org/api-entities/sources/source-object#apc_usd) * [`cited_by_count`](https://docs.openalex.org/api-entities/sources/source-object#cited_by_count) * [`has_issn`](https://docs.openalex.org/api-entities/sources/filter-sources#has_issn) * [`continent`](https://docs.openalex.org/api-entities/geo/continents#group-by-continent) * [`country_code`](https://docs.openalex.org/api-entities/sources/source-object#country_code) * [`host_organization`](https://docs.openalex.org/api-entities/sources/source-object#host_organization) (alias: `host_organization.id`) * [`host_organization_lineage`](https://docs.openalex.org/api-entities/sources/source-object#host_organization_lineage) (alias: `host_organization.id`) * [`is_global_south`](https://docs.openalex.org/api-entities/geo/regions#group-by-global-south) * [`is_core`](https://docs.openalex.org/api-entities/sources/source-object#is_core) * [`is_in_doaj`](https://docs.openalex.org/api-entities/sources/source-object#is_in_doaj) * [`is_oa`](https://docs.openalex.org/api-entities/sources/source-object#is_oa) * [`issn`](https://docs.openalex.org/api-entities/sources/source-object#issn) * [`publisher`](https://docs.openalex.org/api-entities/sources/source-object#publisher) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/sources/source-object#summary_stats) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/sources/source-object#summary_stats) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/sources/source-object#summary_stats) * [`type`](https://docs.openalex.org/api-entities/sources/source-object#type) * [`works_count`](https://docs.openalex.org/api-entities/sources/source-object#works_count) [PreviousSearch sources](https://docs.openalex.org/api-entities/sources/search-sources) [NextInstitutions](https://docs.openalex.org/api-entities/institutions) Last updated 22 days ago --- # Topics | OpenAlex technical documentation Works in OpenAlex are tagged with Topics using an automated system that takes into account the available information about the work, including title, abstract, source (journal) name, and citations. There are around 4,500 Topics. Works are assigned topics using a model that assigns scores for each topic for a work. The highest-scoring topic is that work's [`primary_topic`](https://docs.openalex.org/api-entities/works/work-object#primary_topic) . We also provide additional highly ranked topics for works, in [Work.topics](https://docs.openalex.org/api-entities/works/work-object#topics) . To learn more about how OpenAlex topics work in general, see [the Topics page at OpenAlex help pages](https://help.openalex.org/hc/en-us/articles/24736129405719-Topics) . For a detailed description of the methods behind OpenAlex Topics, see our paper: ["OpenAlex: End-to-End Process for Topic Classification"](https://docs.google.com/document/d/1bDopkhuGieQ4F8gGNj7sEc8WSE8mvLZS/edit?usp=sharing&ouid=106329373929967149989&rtpof=true&sd=true) . The code and model are available at [`https://github.com/ourresearch/openalex-topic-classification`](https://github.com/ourresearch/openalex-topic-classification) . [](https://docs.openalex.org/api-entities/topics#whats-next) What's next ----------------------------------------------------------------------------- Learn more about what you can do with topics: * [The Topic object](https://docs.openalex.org/api-entities/topics/topic-object) * [Get a single topic](https://docs.openalex.org/api-entities/topics/get-a-single-topic) * [Get lists of topics](https://docs.openalex.org/api-entities/topics/get-lists-of-topics) * [Filter topics](https://docs.openalex.org/api-entities/topics/filter-topics) * [Search topics](https://docs.openalex.org/api-entities/topics/search-topics) * [Group topics](https://docs.openalex.org/api-entities/topics/group-topics) [PreviousGroup institutions](https://docs.openalex.org/api-entities/institutions/group-institutions) [NextTopic object](https://docs.openalex.org/api-entities/topics/topic-object) Last updated 22 days ago --- # Institutions | OpenAlex technical documentation Institutions are universities and other organizations to which authors claim affiliations. OpenAlex indexes about 109,000 institutions. * Get a list of OpenAlex institutions: [`https://api.openalex.org/institutions`](https://api.openalex.org/institutions) The [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for institutions is the ROR ID. All institutions in OpenAlex have ROR IDs. Our information about institutions comes from metadata found in Crossref, PubMed, ROR, MAG, and publisher websites. In order to link institutions to works, we parse every affiliation listed by every author. These affiliation strings can be quite messy, so we’ve trained an algorithm to interpret them and extract the actual institutions with reasonably high reliability. For a simple example: we will treat both “MIT, Boston, USA” and “Massachusetts Institute of Technology” as the same institution ([https://ror.org/042nb2s44](https://ror.org/042nb2s44) ). Institutions are linked to works via the [`works.authorships`](https://docs.openalex.org/api-entities/works/work-object#authorships) property. Most papers use raw strings to enumerate author affiliations (eg "Univ. of Florida, Gainesville FL"). Parsing these determine the actual institution the author is talking about is nontrivial; you can find more information about how we do it, as well as downloading code, models, and test sets, [here on GitHub.](https://github.com/ourresearch/openalex-institution-parsing) [](https://docs.openalex.org/api-entities/institutions#whats-next) What's next ----------------------------------------------------------------------------------- Learn more about what you can do with institutions: * [The Institution object](https://docs.openalex.org/api-entities/institutions/institution-object) * [Get a single institution](https://docs.openalex.org/api-entities/institutions/get-a-single-institution) * [Get lists of institutions](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions) * [Filter institutions](https://docs.openalex.org/api-entities/institutions/filter-institutions) * [Search institutions](https://docs.openalex.org/api-entities/institutions/search-institutions) * [Group institutions](https://docs.openalex.org/api-entities/institutions/group-institutions) [PreviousGroup sources](https://docs.openalex.org/api-entities/sources/group-sources) [NextInstitution object](https://docs.openalex.org/api-entities/institutions/institution-object) Last updated 22 days ago --- # Get lists of sources | OpenAlex technical documentation You can get lists of sources: * Get _all_ sources in OpenAlex [https://api.openalex.org/sources](https://api.openalex.org/sources) Which returns a response like this: Copy { "meta": { "count": 226727, "db_response_time_ms": 32, "page": 1, "per_page": 25 }, "results": [\ {\ "id": "https://openalex.org/S2764455111",\ "issn_l": null,\ "issn": null,\ "display_name": "PubMed Central",\ // more fields (removed to save space)\ },\ {\ "id": "https://openalex.org/S4306400806",\ "issn_l": null,\ "issn": null,\ "display_name": "PubMed Central - Europe PMC",\ // more fields (removed to save space)\ },\ // more results (removed to save space)\ ], "group_by": [] } [](https://docs.openalex.org/api-entities/sources/get-lists-of-sources#page-and-sort-sources) Page and sort sources ------------------------------------------------------------------------------------------------------------------------ By default we return 25 results per page. You can change this default and [page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) through sources with the `per-page` and `page` parameters: * Get the second page of sources results, with 50 results returned per page [https://api.openalex.org/sources?per-page=50&page=2](https://api.openalex.org/sources?per-page=50&page=2) You also can [sort results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) with the `sort` parameter: * Sort sources by cited by count, descending https://api.openalex.org/sources?sort=cited\_by\_count:desc Continue on to learn how you can [filter](https://docs.openalex.org/api-entities/sources/filter-sources) and [search](https://docs.openalex.org/api-entities/sources/search-sources) lists of sources. [](https://docs.openalex.org/api-entities/sources/get-lists-of-sources#sample-sources) Sample sources ---------------------------------------------------------------------------------------------------------- You can use `sample` to get a random batch of sources. Read more about sampling and how to add a `seed` value [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) . * Get 10 random sources [https://api.openalex.org/sources?sample=10](https://api.openalex.org/sources?sample=10) [](https://docs.openalex.org/api-entities/sources/get-lists-of-sources#select-fields) Select fields -------------------------------------------------------------------------------------------------------- You can use `select` to limit the fields that are returned in a list of sources. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id`, `display_name` and `issn` within sources results [https://api.openalex.org/sources?select=id,display\_name,issn](https://api.openalex.org/sources?select=id,display_name,issn) [PreviousGet a single source](https://docs.openalex.org/api-entities/sources/get-a-single-source) [NextFilter sources](https://docs.openalex.org/api-entities/sources/filter-sources) Last updated 22 days ago * [Page and sort sources](https://docs.openalex.org/api-entities/sources/get-lists-of-sources#page-and-sort-sources) * [Sample sources](https://docs.openalex.org/api-entities/sources/get-lists-of-sources#sample-sources) * [Select fields](https://docs.openalex.org/api-entities/sources/get-lists-of-sources#select-fields) --- # Search sources | OpenAlex technical documentation The best way to search for sources is to use the `search` query parameter, which searches across [`display_name`](https://docs.openalex.org/api-entities/sources/source-object#display_name) , [`alternate_titles`](https://docs.openalex.org/api-entities/sources/source-object#alternate_titles) , and [`abbreviated_title`](https://docs.openalex.org/api-entities/sources/source-object#abbreviated_title) . Example: * Search for the abbreviated version of the Journal of the American Chemical Society "`jacs`": [https://api.openalex.org/sources?search=jacs](https://api.openalex.org/sources?search=jacs) You can read more about search [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. [](https://docs.openalex.org/api-entities/sources/search-sources#search-a-specific-field) Search a specific field ---------------------------------------------------------------------------------------------------------------------- You can also use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , allowing you to fine-tune the fields you're searching over. To do this, you append `.search` to the end of the property you are filtering for: * Get sources with "nature" in the title: [https://api.openalex.org/sources?filter=display\_name.search:nature](https://api.openalex.org/sources?filter=display_name.search:nature) The following fields can be searched as a filter within sources: Search filter Field that is searched [`display_name.search`](https://docs.openalex.org/api-entities/sources/filter-sources#display_name.search) [`display_name`](https://docs.openalex.org/api-entities/sources/source-object#display_name) You can also use the filter `default.search`, which works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/sources/search-sources#search-sources) . [](https://docs.openalex.org/api-entities/sources/search-sources#autocomplete-sources) Autocomplete sources ---------------------------------------------------------------------------------------------------------------- You can autocomplete sources to create a very fast type-ahead style search function: * Autocomplete sources with "neuro" in the display\_name: https://api.openalex.org/autocomplete/sources?q=neuro This returns a list of sources with the publisher set as the hint: Copy { "results": [\ {\ "id": "https://openalex.org/S5555990",\ "display_name": "The Journal of Neuroscience",\ "hint": "Society for Neuroscience",\ "cited_by_count": 4274712,\ "works_count": 40376,\ "entity_type": "source",\ "external_id": "0270-6474"\ },\ // more results\ ] } Read more in the [autocomplete page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) in the API guide. [PreviousFilter sources](https://docs.openalex.org/api-entities/sources/filter-sources) [NextGroup sources](https://docs.openalex.org/api-entities/sources/group-sources) Last updated 22 days ago * [Search a specific field](https://docs.openalex.org/api-entities/sources/search-sources#search-a-specific-field) * [Autocomplete sources](https://docs.openalex.org/api-entities/sources/search-sources#autocomplete-sources) --- # Topic object | OpenAlex technical documentation These are the fields in a topic object. When you use the API to get a [single topic](https://docs.openalex.org/api-entities/topics/get-a-single-topic) or [lists of topics](https://docs.openalex.org/api-entities/topics/get-lists-of-topics) , this is what's returned. ### [](https://docs.openalex.org/api-entities/topics/topic-object#description) `description` _String:_ A description of this topic, [generated by AI](https://docs.openalex.org/api-entities/topics) . Copy description: "This cluster of papers explores the intersection of artificial intelligence and medicine, focusing on applications in healthcare, medical imaging, clinical decision support, and the ethical challenges associated with AI implementation. It delves into topics such as machine learning, big data, precision medicine, and the potential impact of AI on health equity." ### [](https://docs.openalex.org/api-entities/topics/topic-object#display_name) `display_name` _String:_ The English-language label of the topic. Copy display_name: "Artificial Intelligence in Medicine" ### [](https://docs.openalex.org/api-entities/topics/topic-object#domain) `domain` _Object:_ The ID and the name (`display_name`) for the _domain_ of this topic. The domain is the highest level in the "domain, field, subfield, topic" system, which means it is the least granular. See the [topics overview](https://docs.openalex.org/api-entities/topics) for more explanation and a diagram. Copy domain: { id: 4, display_name: "Health Sciences" } ### [](https://docs.openalex.org/api-entities/topics/topic-object#field) `field` _Object:_ The ID and the name (`display_name`) for the _field_ of this topic. The field is the second-highest level in the "domain, field, subfield, topic" system, which means it is the second-least granular. See the [topics overview](https://docs.openalex.org/api-entities/topics) for more explanation and a diagram. Copy field: { id: 27, display_name: "Medicine" } ### [](https://docs.openalex.org/api-entities/topics/topic-object#id) `id` _String:_ The OpenAlex ID for this topic. ### [](https://docs.openalex.org/api-entities/topics/topic-object#ids) `ids` _Object:_ All the external identifiers that we know about for this topic. IDs are expressed as URIs whenever possible. Possible ID types: * `openalex` (_String:_ this topic's [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) . Same as [`Topic.id`](https://docs.openalex.org/api-entities/topics/topic-object#id) ) * `wikipedia` (_String:_ this topic's Wikipedia page URL) ### [](https://docs.openalex.org/api-entities/topics/topic-object#keywords) `keywords` _List:_ Keywords consisting of one or several words each, meant to represent the content of the papers in the topic. These keywords were generated as part of the [AI model](https://docs.openalex.org/api-entities/topics) . For now, they are provided as-is, but we will be providing more support and documenting them more thoroughly. ### [](https://docs.openalex.org/api-entities/topics/topic-object#subfield) `subfield` _Object:_ The ID and the name (`display_name`) for the _subfield_ of this topic. The subfield is the third-highest level in the "domain, field, subfield, topic" system, which means it is the third-least granular. See the [topics overview](https://docs.openalex.org/api-entities/topics) for more explanation and a diagram. ### [](https://docs.openalex.org/api-entities/topics/topic-object#updated_date) `updated_date` _String:_ The last time anything in this topic object changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. This date is updated for _any change at all_, including increases in various counts. ### [](https://docs.openalex.org/api-entities/topics/topic-object#works_count) `works_count` _Integer:_ The number of works tagged with this topic. [PreviousTopics](https://docs.openalex.org/api-entities/topics) [NextGet a single topic](https://docs.openalex.org/api-entities/topics/get-a-single-topic) Last updated 22 days ago * [description](https://docs.openalex.org/api-entities/topics/topic-object#description) * [display\_name](https://docs.openalex.org/api-entities/topics/topic-object#display_name) * [domain](https://docs.openalex.org/api-entities/topics/topic-object#domain) * [field](https://docs.openalex.org/api-entities/topics/topic-object#field) * [id](https://docs.openalex.org/api-entities/topics/topic-object#id) * [ids](https://docs.openalex.org/api-entities/topics/topic-object#ids) * [keywords](https://docs.openalex.org/api-entities/topics/topic-object#keywords) * [subfield](https://docs.openalex.org/api-entities/topics/topic-object#subfield) * [updated\_date](https://docs.openalex.org/api-entities/topics/topic-object#updated_date) * [works\_count](https://docs.openalex.org/api-entities/topics/topic-object#works_count) Copy id: "https://openalex.org/T11636" Copy ids: { openalex: "https://openalex.org/T11636", wikipedia: "https://en.wikipedia.org/wiki/Artificial_intelligence_in_healthcare" } Copy keywords: [\ "Artificial Intelligence",\ "Machine Learning",\ "Healthcare",\ "Medical Imaging",\ "Clinical Decision Support",\ ...\ ] Copy subfield: { id: 2718, display_name: "Health Informatics" } Copy updated_date: "2024-02-05T05:00:03.798420" Copy works_count: 21737 --- # Publishers | OpenAlex technical documentation Publishers are companies and organizations that distribute journal articles, books, and theses. OpenAlex indexes about 10,000 publishers. * Get a list of OpenAlex publishers: [`https://api.openalex.org/publishers`](https://api.openalex.org/publishers) Our publisher data is closely tied to the publisher information in Wikidata. So the [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for OpenAlex publishers is a Wikidata ID, and almost every publisher has one. Publishers are linked to sources through the [`host_organization`](https://docs.openalex.org/api-entities/sources/source-object#host_organization) field. [](https://docs.openalex.org/api-entities/publishers#whats-next) What's next --------------------------------------------------------------------------------- Learn more about what you can do with publishers: * [The Publisher object](https://docs.openalex.org/api-entities/publishers/publisher-object) * [Get a single publisher](https://docs.openalex.org/api-entities/publishers/get-a-single-publisher) * [Get lists of publishers](https://docs.openalex.org/api-entities/publishers/get-lists-of-publishers) * [Filter publishers](https://docs.openalex.org/api-entities/publishers/filter-publishers) * [Search publishers](https://docs.openalex.org/api-entities/publishers/search-publishers) * [Group publishers](https://docs.openalex.org/api-entities/publishers/group-publishers) [PreviousKeywords](https://docs.openalex.org/api-entities/keywords) [NextPublisher object](https://docs.openalex.org/api-entities/publishers/publisher-object) Last updated 22 days ago --- # Filter authors | OpenAlex technical documentation You can filter authors with the `filter` parameter: * Get authors that have an ORCID [https://api.openalex.org/authors?filter=has\_orcid:true](https://api.openalex.org/authors?filter=has_orcid:true) It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query. ### [](https://docs.openalex.org/api-entities/authors/filter-authors#authors-attribute-filters) `/authors` attribute filters You can filter using these attributes of the `Author` entity object (click each one to view their documentation on the [`Author`](https://docs.openalex.org/api-entities/authors/author-object) object page): * [`affiliations.institution.country_code`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`affiliations.institution.id`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`affiliations.institution.lineage`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`affiliations.institution.ror`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`affiliations.institution.type`](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [`cited_by_count`](https://docs.openalex.org/api-entities/authors/author-object#cited_by_count) * [`ids.openalex`](https://docs.openalex.org/api-entities/authors/author-object#ids) (alias: `openalex`) * [`last_known_institution.country_code`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`last_known_institution.id`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`last_known_institution.lineage`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`last_known_institution.ror`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`last_known_institution.type`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) * [`orcid`](https://docs.openalex.org/api-entities/authors/author-object#orcid) * [`scopus`](https://docs.openalex.org/api-entities/authors/author-object#ids) (the author's scopus ID, as an integer) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/authors/author-object#summary_stats) (accepts float, null, !null, can use range queries such as < >) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/authors/author-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/authors/author-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`works_count`](https://docs.openalex.org/api-entities/authors/author-object#works_count) * [`x_concepts.id`](https://docs.openalex.org/api-entities/authors/author-object#x_concepts) (alias: `concepts.id` or `concept.id`) -- will be deprecated soon Want to filter by `last_known_institution.display_name`? This is a two-step process: 1. Find the `institution.id` by searching institutions by `display_name`. 2. Filter works by `last_known_institution.id`. To learn more about why we do it this way, [see here.](https://docs.openalex.org/api-entities/works/search-works#why-cant-i-search-by-name-of-related-entity-author-name-institution-name-etc.) ### [](https://docs.openalex.org/api-entities/authors/filter-authors#authors-convenience-filters) `/authors` convenience filters These filters aren't attributes of the [`Author` object](https://docs.openalex.org/api-entities/authors/author-object) , but they're included to address some common use cases: #### [](https://docs.openalex.org/api-entities/authors/filter-authors#default.search) `default.search` Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/authors/search-authors#search-authors) for Authors. #### [](https://docs.openalex.org/api-entities/authors/filter-authors#display_name.search) `display_name.search` Value: a search string Returns: Authors whose [`display_name`](https://docs.openalex.org/api-entities/authors/author-object#display_name) contains the given string; see the [search filter](https://docs.openalex.org/api-entities/authors/search-authors#search-a-specific-field) for details. * Get authors named "tupolev": [`https://api.openalex.org/authors?filter=display_name.search:tupolev`](https://api.openalex.org/authors?filter=display_name.search:tupolev) #### [](https://docs.openalex.org/api-entities/authors/filter-authors#has_orcid) `has_orcid` Value: a Boolean (`true` or `false`) Returns: authors that have or lack an [orcid](https://docs.openalex.org/api-entities/authors/author-object#orcid) , depending on the given value. * Get the authors that have an ORCID: \`\`[`https://api.openalex.org/authors?filter=has_orcid:true`](https://api.openalex.org/authors?filter=has_orcid:true) #### [](https://docs.openalex.org/api-entities/authors/filter-authors#last_known_institution.continent) `last_known_institution.continent` Value: a String with a valid [continent filter](https://docs.openalex.org/api-entities/geo/continents#filter-by-continent) Returns: authors where where the last known institution is in the chosen continent. * Get authors where the last known institution is located in Africa [https://api.openalex.org/authors?filter=last\_known\_institution.continent:africa](https://api.openalex.org/authors?filter=last_known_institution.continent:africa) #### [](https://docs.openalex.org/api-entities/authors/filter-authors#last_known_institution.is_global_south) `last_known_institution.is_global_south` Value: a Boolean (`true` or `false`) Returns: works where at least _one_ of the author's institutions is in the [Global South](https://docs.openalex.org/api-entities/geo/regions#global-south) . * Get authors where the last known institution is located in the Global South [https://api.openalex.org/authors?filter=last\_known\_institution.is\_global\_south:true](https://api.openalex.org/authors?filter=last_known_institution.is_global_south:true) [PreviousGet lists of authors](https://docs.openalex.org/api-entities/authors/get-lists-of-authors) [NextSearch authors](https://docs.openalex.org/api-entities/authors/search-authors) Last updated 22 days ago * [/authors attribute filters](https://docs.openalex.org/api-entities/authors/filter-authors#authors-attribute-filters) * [/authors convenience filters](https://docs.openalex.org/api-entities/authors/filter-authors#authors-convenience-filters) --- # Get a single source | OpenAlex technical documentation It's easy to get a source from from the API with: `/sources/`. Here's an example: * Get the source with the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) `S137773608`: [https://api.openalex.org/sources/S137773608](https://api.openalex.org/sources/S137773608) That will return an [`Source`](https://docs.openalex.org/api-entities/sources/source-object) object, describing everything OpenAlex knows about the source with that ID: Copy { "id": "https://openalex.org/S137773608", "issn_l": "0028-0836", "issn": [\ "1476-4687",\ "0028-0836"\ ], "display_name": "Nature", // other fields removed for brevity } You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . Sources are also available via an alias: `/journals` ### [](https://docs.openalex.org/api-entities/sources/get-a-single-source#external-ids) External IDs You can look up journals using external IDs such as an ISSN: * Get the source with ISSN: `2041-1723`: [`https://api.openalex.org/sources/issn:2041-1723`](https://api.openalex.org/sources/issn:2041-1723) Available external IDs for sources are: External ID URN ISSN `issn` Fatcat `fatcat` Microsoft Academic Graph (MAG) `mag` Wikidata `wikidata` ### [](https://docs.openalex.org/api-entities/sources/get-a-single-source#select-fields) Select fields You can use `select` to limit the fields that are returned in a source object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` for a source object [https://api.openalex.org/sources/S137773608?select=id,display\_name](https://api.openalex.org/sources/S137773608?select=id,display_name) [PreviousSource object](https://docs.openalex.org/api-entities/sources/source-object) [NextGet lists of sources](https://docs.openalex.org/api-entities/sources/get-lists-of-sources) Last updated 21 days ago * [External IDs](https://docs.openalex.org/api-entities/sources/get-a-single-source#external-ids) * [Select fields](https://docs.openalex.org/api-entities/sources/get-a-single-source#select-fields) --- # Filter institutions | OpenAlex technical documentation You can filter institutions with the `filter` parameter: * Get institutions that are located in Canada [https://api.openalex.org/institutions?filter=country\_code:ca](https://api.openalex.org/institutions?filter=country_code:ca) It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query ### [](https://docs.openalex.org/api-entities/institutions/filter-institutions#institutions-attribute-filters) `/institutions` attribute filters You can filter using these attributes of the `Institution` entity object (click each one to view their documentation on the [`Institution`](https://docs.openalex.org/api-entities/institutions/institution-object) object page): * [`cited_by_count`](https://docs.openalex.org/api-entities/institutions/institution-object#cited_by_count) * [`country_code`](https://docs.openalex.org/api-entities/institutions/institution-object#country_code) * [`is_super_system`](https://docs.openalex.org/api-entities/institutions/institution-object#is_super_system) * [`lineage`](https://docs.openalex.org/api-entities/institutions/institution-object#lineage) : OpenAlex ID for an [`Institution`](https://docs.openalex.org/api-entities/institutions) * [`openalex`](https://docs.openalex.org/api-entities/institutions/institution-object#id) : the OpenAlex ID of the Institution * [`repositories.host_organization`](https://docs.openalex.org/api-entities/institutions/institution-object#repositories) : OpenAlex ID for an [`Institution`](https://docs.openalex.org/api-entities/institutions) * [`repositories.host_organization_lineage`](https://docs.openalex.org/api-entities/institutions/institution-object#repositories) : OpenAlex ID for an [`Institution`](https://docs.openalex.org/api-entities/institutions) * [`repositories.id`](https://docs.openalex.org/api-entities/institutions/institution-object#repositories) : the OpenAlex ID of a repository (a [`Source`](https://docs.openalex.org/api-entities/sources) ) * [`ror`](https://docs.openalex.org/api-entities/institutions/institution-object#ror) : the ROR ID of the Institution * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/institutions/institution-object#summary_stats) (accepts float, null, !null, can use range queries such as < >) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/institutions/institution-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/institutions/institution-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`type`](https://docs.openalex.org/api-entities/institutions/institution-object#type) * [`works_count`](https://docs.openalex.org/api-entities/institutions/institution-object#works_count) * [`x_concepts.id`](https://docs.openalex.org/api-entities/institutions/institution-object#x_concepts) (alias: `concepts.id` or `concept.id`) -- will be deprecated soon ### [](https://docs.openalex.org/api-entities/institutions/filter-institutions#institutions-convenience-filters) `/institutions` convenience filters These filters aren't attributes of the [`Institution`](https://docs.openalex.org/api-entities/institutions/institution-object) object, but they're included to address some common use cases: #### [](https://docs.openalex.org/api-entities/institutions/filter-institutions#continent) `continent` Value: a String with a valid [continent filter](https://docs.openalex.org/api-entities/geo/continents#filter-by-continent) Returns: institutions that are located in the chosen continent. * Get institutions that are located in South America [https://api.openalex.org/institutions?filter=continent:south\_america](https://api.openalex.org/institutions?filter=continent:south_america) #### [](https://docs.openalex.org/api-entities/institutions/filter-institutions#default.search) `default.search` Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/institutions/search-institutions#search-institutions) for Institutions. #### [](https://docs.openalex.org/api-entities/institutions/filter-institutions#display_name.search) `display_name.search` Value: a search string Returns: institutions with a [`display_name`](https://docs.openalex.org/api-entities/institutions/institution-object#display_name) containing the given string; see the [search page](https://docs.openalex.org/api-entities/institutions/search-institutions#search-a-specific-field) for details. * Get institutions with names containing "technology": [`https://api.openalex.org/institutions?filter=display_name.search:technology`](https://api.openalex.org/institutions?filter=display_name.search:technology) In most cases, you should use the [`search` parameter](https://docs.openalex.org/api-entities/institutions/search-institutions) instead of this filter because it uses a better search algorithm. #### [](https://docs.openalex.org/api-entities/institutions/filter-institutions#has_ror) `has_ror` Value: a Boolean (`true` or `false`) Returns: institutions that have or lack a [ROR ID](https://docs.openalex.org/api-entities/institutions/institution-object#ror) , depending on the given value. * Get institutions without ROR IDs: [`https://api.openalex.org/institutions?filter=has_ror:false`](https://api.openalex.org/institutions?filter=has_ror:false) #### [](https://docs.openalex.org/api-entities/institutions/filter-institutions#is_global_south) `is_global_south` Value: a Boolean (`true` or `false`) Returns: institutions that are located in the [Global South](https://docs.openalex.org/api-entities/geo/regions#global-south) . * Get institutions that are located in the Global South [https://api.openalex.org/institutions?filter=is\_global\_south:true](https://api.openalex.org/institutions?filter=is_global_south:true) [PreviousGet lists of institutions](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions) [NextSearch institutions](https://docs.openalex.org/api-entities/institutions/search-institutions) Last updated 22 days ago * [/institutions attribute filters](https://docs.openalex.org/api-entities/institutions/filter-institutions#institutions-attribute-filters) * [/institutions convenience filters](https://docs.openalex.org/api-entities/institutions/filter-institutions#institutions-convenience-filters) --- # Get lists of authors | OpenAlex technical documentation You can get lists of authors: * Get _all_ authors in OpenAlex [`https://api.openalex.org/authors`](https://api.openalex.org/authors) Which returns a response like this: Copy { "meta": { "count": 93011659, "db_response_time_ms": 150, "page": 1, "per_page": 25 }, "results": [\ {\ "id": "https://openalex.org/A5053780153",\ // more fields (removed to save space)\ },\ {\ "id": "https://openalex.org/A5032245741",\ // more fields (removed to save space)\ },\ // more results (removed to save space)\ ], "group_by": [] } [](https://docs.openalex.org/api-entities/authors/get-lists-of-authors#page-and-sort-authors) Page and sort authors ------------------------------------------------------------------------------------------------------------------------ By default we return 25 results per page. You can change this default and [page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) through works with the `per-page` and `page` parameters: * Get the second page of authors results, with 50 results returned per page [`https://api.openalex.org/authors?per-page=50\&page=2`](https://api.openalex.org/authors?per-page=50&page=2) You also can [sort results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) with the `sort` parameter: * Sort authors by cited by count, descending [`https://api.openalex.org/authors?sort=cited\_by\_count:desc`](https://api.openalex.org/authors?sort=cited_by_count:desc) Continue on to learn how you can [filter](https://docs.openalex.org/api-entities/authors/filter-authors) and [search](https://docs.openalex.org/api-entities/authors/search-authors) lists of authors. [](https://docs.openalex.org/api-entities/authors/get-lists-of-authors#sample-authors) Sample authors ---------------------------------------------------------------------------------------------------------- You can use `sample` to get a random batch of authors. Read more about sampling and how to add a `seed` value [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) . * Get 25 random authors [`https://api.openalex.org/authors?sample=25`](https://api.openalex.org/authors?sample=25) [](https://docs.openalex.org/api-entities/authors/get-lists-of-authors#select-fields) Select fields -------------------------------------------------------------------------------------------------------- You can use `select` to limit the fields that are returned in a list of authors. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` and `orcid` within authors results [`https://api.openalex.org/authors?select=id,display\_name,orcid`](https://api.openalex.org/authors?select=id,display_name,orcid) [PreviousGet a single author](https://docs.openalex.org/api-entities/authors/get-a-single-author) [NextFilter authors](https://docs.openalex.org/api-entities/authors/filter-authors) Last updated 22 days ago * [Page and sort authors](https://docs.openalex.org/api-entities/authors/get-lists-of-authors#page-and-sort-authors) * [Sample authors](https://docs.openalex.org/api-entities/authors/get-lists-of-authors#sample-authors) * [Select fields](https://docs.openalex.org/api-entities/authors/get-lists-of-authors#select-fields) --- # Search institutions | OpenAlex technical documentation The best way to search for institutions is to use the `search` query parameter, which searches the [`display_name`](https://docs.openalex.org/api-entities/institutions/institution-object#display_name) , the [`display_name_alternatives`](https://docs.openalex.org/api-entities/institutions/institution-object#display_name_alternatives) , and the [`display_name_acronyms`](https://docs.openalex.org/api-entities/institutions/institution-object#display_name_acronyms) . Example: * Search institutions for San Diego State University: [`https://api.openalex.org/institutions?search=san diego state university`](https://api.openalex.org/institutions?search=san%20diego%20state%20university) You can read more about search [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. [](https://docs.openalex.org/api-entities/institutions/search-institutions#search-a-specific-field) Search a specific field -------------------------------------------------------------------------------------------------------------------------------- You can also use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , allowing you to fine-tune the fields you're searching over. To do this, you append `.search` to the end of the property you are filtering for: * Get institutions with "florida" in the `display_name`: [https://api.openalex.org/institutions?filter=display\_name.search:florida](https://api.openalex.org/institutions?filter=display_name.search:florida) The following field can be searched as a filter within institutions: Search filter Field that is searched [`display_name.search`](https://docs.openalex.org/api-entities/institutions/filter-institutions#display_name.search) [`display_name`](https://docs.openalex.org/api-entities/institutions/institution-object#display_name) You can also use the filter `default.search`, which works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/institutions/search-institutions#search-institutions) . [](https://docs.openalex.org/api-entities/institutions/search-institutions#autocomplete-institutions) Autocomplete institutions ------------------------------------------------------------------------------------------------------------------------------------ You can autocomplete institutions to create a very fast type-ahead style search function: * Autocomplete institutions with "harv" in the [`display_name`](https://docs.openalex.org/api-entities/institutions/institution-object#display_name) : [https://api.openalex.org/autocomplete/institutions?q=harv](https://api.openalex.org/autocomplete/institutions?q=harv) This returns a list of institutions with the institution location set as the hint: Copy { "results": [\ {\ "id": "https://openalex.org/I136199984",\ "display_name": "Harvard University",\ "hint": "Cambridge, USA",\ "cited_by_count": 37792327,\ "works_count": 242547,\ "entity_type": "institution",\ "external_id": "https://ror.org/03vek6s52"\ },\ ...\ ] } Read more in the [autocomplete page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) in the API guide. [PreviousFilter institutions](https://docs.openalex.org/api-entities/institutions/filter-institutions) [NextGroup institutions](https://docs.openalex.org/api-entities/institutions/group-institutions) Last updated 22 days ago * [Search a specific field](https://docs.openalex.org/api-entities/institutions/search-institutions#search-a-specific-field) * [Autocomplete institutions](https://docs.openalex.org/api-entities/institutions/search-institutions#autocomplete-institutions) --- # Get a single award | OpenAlex technical documentation It's easy to get an award from the API with: `/awards/`. Here's an example: * Get the award with the OpenAlex ID `G5453342221`: [`https://api.openalex.org/awards/G5453342221`](https://api.openalex.org/awards/G5453342221) That will return an [`Award`](https://docs.openalex.org/api-entities/awards/award-object) object, describing everything OpenAlex knows about the award with that ID. You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . ### [](https://docs.openalex.org/api-entities/awards/get-a-single-award#external-ids) External IDs You can look up awards using external IDs such as DOI: * Get the award with DOI `10.3030/633053`: [`https://api.openalex.org/awards/doi:10.3030/633053`](https://api.openalex.org/awards/doi:10.3030/633053) ### [](https://docs.openalex.org/api-entities/awards/get-a-single-award#select-fields) Select fields You can use `select` to limit the fields that are returned in an award object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` for an award: [`https://api.openalex.org/awards/G5453342221?select=id,display_name`](https://api.openalex.org/awards/G5453342221?select=id,display_name) [PreviousAward object](https://docs.openalex.org/api-entities/awards/award-object) [NextGet lists of awards](https://docs.openalex.org/api-entities/awards/get-lists-of-awards) Last updated 22 days ago * [External IDs](https://docs.openalex.org/api-entities/awards/get-a-single-award#external-ids) * [Select fields](https://docs.openalex.org/api-entities/awards/get-a-single-award#select-fields) --- # Get a single publisher | OpenAlex technical documentation It's easy to get a publisher from from the API with: `/publishers/`. Here's an example: * Get the publisher with the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) `P4310319965`: [https://api.openalex.org/publishers/P4310319965](https://api.openalex.org/publishers/P4310319965) That will return a [`Publisher`](https://docs.openalex.org/api-entities/publishers/publisher-object) object, describing everything OpenAlex knows about the publisher with that ID: Copy { "id": "https://openalex.org/P4310319965", "display_name": "Springer Nature", "alternate_titles": [\ "エイプレス",\ "Springer Nature Group",\ "施普林格-自然出版集团"\ ], "hierarchy_level": 0, // other fields removed for brevity } You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . ### [](https://docs.openalex.org/api-entities/publishers/get-a-single-publisher#external-ids) External IDs You can look up publishers using external IDs such as a Wikidata ID: * Get the publisher with Wikidata ID Q1479654: [https://api.openalex.org/publishers/wikidata:Q1479654](https://api.openalex.org/publishers/wikidata:Q1479654) Available external IDs for publishers are: External ID URN ROR `ror` Wikidata `wikidata` ### [](https://docs.openalex.org/api-entities/publishers/get-a-single-publisher#select-fields) Select fields You can use `select` to limit the fields that are returned in a publisher object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` for a publisher object [https://api.openalex.org/publishers/P4310319965?select=id,display\_name](https://api.openalex.org/publishers/P4310319965?select=id,display_name) [PreviousPublisher object](https://docs.openalex.org/api-entities/publishers/publisher-object) [NextGet lists of publishers](https://docs.openalex.org/api-entities/publishers/get-lists-of-publishers) Last updated 22 days ago * [External IDs](https://docs.openalex.org/api-entities/publishers/get-a-single-publisher#external-ids) * [Select fields](https://docs.openalex.org/api-entities/publishers/get-a-single-publisher#select-fields) --- # Search authors | OpenAlex technical documentation The best way to search for authors is to use the `search` query parameter, which searches the [`display_name`](https://docs.openalex.org/api-entities/authors/author-object#display_name) and the [`display_name_alternatives`](https://docs.openalex.org/api-entities/authors/author-object#display_name_alternatives) fields. Example: * Get works with the author name "Carl Sagan": [`https://api.openalex.org/authors?search=carl sagan`](https://api.openalex.org/authors?search=carl%20sagan) Searching without a middle initial returns names with _and_ without middle initials. So a search for "John Smith" will also return "John W. Smith". Names with diacritics are flexible as well. So a search for David Tarrago can return David Tarragó, and a search for David Tarragó can return David Tarrago. When searching with a diacritic, diacritic versions of the names are prioritized in order to honor the original form of the author's name. Read more about our handling of diacritics [here](https://blog.ourresearch.org/author-search-in-openalex-improved-handling-of-diacritics-within-names/) . You can read more in the [search page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) in the API Guide. It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. [](https://docs.openalex.org/api-entities/authors/search-authors#search-a-specific-field) Search a specific field ---------------------------------------------------------------------------------------------------------------------- You can also use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , by appending `.search` to the end of the property you are filtering for: * Get authors with the name "john smith" in the display\_name: [`https://api.openalex.org/authors?filter=display\_name.search:john smith`](https://api.openalex.org/authors?filter=display_name.search:john%20smith) When searching for authors, there is no difference when using the `search` parameter or the filter `display_name.search`, since display\_name is the only field searched when finding authors. Search filter Field that is searched [`display_name.search`](https://docs.openalex.org/api-entities/authors/filter-authors#display_name.search) [`display_name`](https://docs.openalex.org/api-entities/authors/author-object#display_name) You can also use the filter `default.search`, which works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/authors/search-authors#search-authors) . [](https://docs.openalex.org/api-entities/authors/search-authors#autocomplete-authors) Autocomplete authors ---------------------------------------------------------------------------------------------------------------- You can autocomplete authors to create a very fast type-ahead style search function: * Autocomplete authors with "ronald sw" in the display name: [`https://api.openalex.org/autocomplete/authors?q=ronald sw`](https://api.openalex.org/autocomplete/authors?q=ronald%20sw) This returns a list of authors with their last known affiliated institution as the hint: Read more about [autocomplete](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) . [PreviousFilter authors](https://docs.openalex.org/api-entities/authors/filter-authors) [NextGroup authors](https://docs.openalex.org/api-entities/authors/group-authors) Last updated 22 days ago * [Search a specific field](https://docs.openalex.org/api-entities/authors/search-authors#search-a-specific-field) * [Autocomplete authors](https://docs.openalex.org/api-entities/authors/search-authors#autocomplete-authors) Copy { "results": [\ {\ "id": "https://openalex.org/A5007433649",\ "display_name": "Ronald Swanstrom",\ "hint": "University of North Carolina at Chapel Hill, USA",\ "cited_by_count": 19142,\ "works_count": 339,\ "entity_type": "author",\ "external_id": "https://orcid.org/0000-0001-7777-0773",\ "filter_key": "authorships.author.id"\ },\ ...\ ] } --- # Keywords | OpenAlex technical documentation Works in OpenAlex are tagged with Keywords using an automated system based on Topics. To learn more about how OpenAlex Keywords work in general, see [the Keywords page at OpenAlex help pages](https://help.openalex.org/how-it-works/keywords) . [](https://docs.openalex.org/api-entities/keywords#keyword-object) Keyword object -------------------------------------------------------------------------------------- These are the fields in a keyword object. When you use the API to get a [single keyword](https://docs.openalex.org/api-entities/keywords#get-a-single-keyword) or [lists of keywords](https://docs.openalex.org/api-entities/keywords#get-a-list-of-keywords) , this is what's returned. ### [](https://docs.openalex.org/api-entities/keywords#cited_by_count) `cited_by_count` _Integer:_ The number of citations to works that have been tagged with this keyword. Or less formally: the number of citations to this keyword. For example, if there are just two works tagged with this keyword and one of them has been cited 10 times, and the other has been cited 1 time, `cited_by_count` for this keyword would be `11`. Copy cited_by_count: 4347000 ### [](https://docs.openalex.org/api-entities/keywords#created_date) `created_date` _String:_ The date this `Keyword` object was created in the OpenAlex dataset, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. Copy created_date: "2024-04-10" ### [](https://docs.openalex.org/api-entities/keywords#display_name) `display_name` _String:_ The English-language label of the keyword. Copy display_name: "Cardiac Imaging" ### [](https://docs.openalex.org/api-entities/keywords#id) `id` _String:_ The OpenAlex ID for this keyword. ### [](https://docs.openalex.org/api-entities/keywords#updated_date) `updated_date` _String:_ The last time anything in this keyword object changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. This date is updated for _any change at all_, including increases in various counts. ### [](https://docs.openalex.org/api-entities/keywords#works_count) `works_count` _Integer:_ The number of works tagged with this keyword. [](https://docs.openalex.org/api-entities/keywords#get-a-single-keyword) Get a single keyword -------------------------------------------------------------------------------------------------- It's easy to get a keyword from the API with: `/keyword/`. Here's an example: * Get the keyword with the ID `cardiac-imaging`: [`https://api.openalex.org/keywords/cardiac-imaging`](https://api.openalex.org/keywords/cardiac-imaging) That will return a [`Keyword`](https://docs.openalex.org/api-entities/keywords#keyword-object) object, describing everything OpenAlex knows about the keyword with that ID: You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . ### [](https://docs.openalex.org/api-entities/keywords#select-fields) Select fields You can use `select` to limit the fields that are returned in a keyword object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` for a keyword object [`https://api.openalex.org/keywords/cardiac-imaging?select=id,display_name`](https://api.openalex.org/keywords/cardiac-imaging?select=id,display_name) [](https://docs.openalex.org/api-entities/keywords#get-a-list-of-keywords) Get a list of keywords ------------------------------------------------------------------------------------------------------ You can get lists of keywords: * Get _all_ keywords in OpenAlex [`https://api.openalex.org/keywords`](https://api.openalex.org/keywords) Which returns a response like this: [](https://docs.openalex.org/api-entities/keywords#filter-keywords) Filter keywords ---------------------------------------------------------------------------------------- You can filter keywords with the `filter` parameter: * Get keywords that are in the subfield "Epidemiology" (id: 2713) [`https://api.openalex.org/keywords?filter=subfield.id:2713`](https://api.openalex.org/keywords?filter=subfield.id:2713) It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query ### [](https://docs.openalex.org/api-entities/keywords#keywords-attribute-filters) `/keywords` attribute filters You can filter using these attributes of the [`Keyword`](https://docs.openalex.org/api-entities/keywords#keyword-object) object: * [`cited_by_count`](https://docs.openalex.org/api-entities/keywords#cited_by_count) * [`id`](https://docs.openalex.org/api-entities/keywords#id) * [`works_count`](https://docs.openalex.org/api-entities/keywords#works_count) ### [](https://docs.openalex.org/api-entities/keywords#keywords-convenience-filters) `/keywords` convenience filters These filters aren't attributes of the [`Keyword`](https://docs.openalex.org/api-entities/keywords#keyword-object) object, but they're included to address some common use cases: #### [](https://docs.openalex.org/api-entities/keywords#default.search) `default.search` Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/keywords#search-keywords) for Keywords. #### [](https://docs.openalex.org/api-entities/keywords#display_name.search) `display_name.search` Value: a search string Returns: keywords with a [`display_name`](https://docs.openalex.org/api-entities/keywords#display_name) containing the given string. * Get keywords with `display_name` containing "artificial" and "intelligence": [`https://api.openalex.org/keywords?filter=display_name.search:artificial+intelligence`](https://api.openalex.org/keywords?filter=display_name.search:artificial+intelligence) [](https://docs.openalex.org/api-entities/keywords#search-keywords) Search keywords ---------------------------------------------------------------------------------------- You can search for keywords using the `search` query parameter, which searches the [`display_name`](https://docs.openalex.org/api-entities/keywords#display_name) fileds. For example: * Search keywords' `display_name` "artificial intelligence": [https://api.openalex.org/keywords?search=artificial intelligence](https://api.openalex.org/keywords?search=artificial%20intelligence) You can read more about search [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. [](https://docs.openalex.org/api-entities/keywords#group-keywords) Group keywords -------------------------------------------------------------------------------------- You can group keywords with the `group_by` parameter: * Get counts of keywords by [`cited_by_count`](https://docs.openalex.org/api-entities/keywords#cited_by_count) : [`https://api.openalex.org/keywords?group_by=cited_by_count`](https://api.openalex.org/keywords?group_by=cited_by_count) Or you can group using one the attributes below. It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. ### [](https://docs.openalex.org/api-entities/keywords#keywords-group_by-attributes) Keywords group\_by attributes * [`cited_by_count`](https://docs.openalex.org/api-entities/keywords#cited_by_count) * [`works_count`](https://docs.openalex.org/api-entities/keywords#works_count) [PreviousGroup topics](https://docs.openalex.org/api-entities/topics/group-topics) [NextPublishers](https://docs.openalex.org/api-entities/publishers) Last updated 22 days ago * [Keyword object](https://docs.openalex.org/api-entities/keywords#keyword-object) * [cited\_by\_count](https://docs.openalex.org/api-entities/keywords#cited_by_count) * [created\_date](https://docs.openalex.org/api-entities/keywords#created_date) * [display\_name](https://docs.openalex.org/api-entities/keywords#display_name) * [id](https://docs.openalex.org/api-entities/keywords#id) * [updated\_date](https://docs.openalex.org/api-entities/keywords#updated_date) * [works\_count](https://docs.openalex.org/api-entities/keywords#works_count) * [Get a single keyword](https://docs.openalex.org/api-entities/keywords#get-a-single-keyword) * [Select fields](https://docs.openalex.org/api-entities/keywords#select-fields) * [Get a list of keywords](https://docs.openalex.org/api-entities/keywords#get-a-list-of-keywords) * [Filter keywords](https://docs.openalex.org/api-entities/keywords#filter-keywords) * [/keywords attribute filters](https://docs.openalex.org/api-entities/keywords#keywords-attribute-filters) * [/keywords convenience filters](https://docs.openalex.org/api-entities/keywords#keywords-convenience-filters) * [Search keywords](https://docs.openalex.org/api-entities/keywords#search-keywords) * [Group keywords](https://docs.openalex.org/api-entities/keywords#group-keywords) * [Keywords group\_by attributes](https://docs.openalex.org/api-entities/keywords#keywords-group_by-attributes) Copy id: "https://openalex.org/keywords/cardiac-imaging" Copy updated_date: "2024-05-09T05:00:03.798420" Copy works_count: 21737 Copy { "id": "https://openalex.org/keywords/cardiac-imaging", "display_name": "Cardiac Imaging", // other fields removed for brevity } Copy { "meta": { "count": 4516, "db_response_time_ms": 10, "page": 1, "per_page": 25, "groups_count": null }, "results": [\ {\ "id": "https://openalex.org/T11475",\ "display_name": "Territorial Governance and Environmental Participation",\ // more fields (removed to save space)\ },\ {\ "id": "https://openalex.org/T13445",\ "display_name": "American Political Thought and History",\ // more fields (removed to save space)\ },\ // more results (removed to save space)\ ], "group_by": [] } --- # Geo | OpenAlex technical documentation While geo is not a core entity within OpenAlex, geography is central to categorizing scholarly data. That's why OpenAlex uses United Nations data to divide the globe into continents and regions that makes filtering data easier. Here are some ways you can filter and group by continents and the [Global South](https://en.wikipedia.org/wiki/Global_North_and_Global_South) . * Get institutions located in South America [`https://api.openalex.org/institutions?filter=continent:south_america`](https://api.openalex.org/institutions?filter=continent:south_america) * Get works where at least one author's institution is located in the Global South [`https://api.openalex.org/works?filter=institutions.is\_global\_south:true`](https://api.openalex.org/works?filter=institutions.is_global_south:true) * Group highly-cited authors by their last known institution's continent [`https://api.openalex.org/authors?group-by=last\_known\_institution.continent\&filter=cited\_by\_count:>100`](https://api.openalex.org/authors?group-by=last_known_institution.continent&filter=cited_by_count:%3E100) [](https://docs.openalex.org/api-entities/geo#whats-next) What's next -------------------------------------------------------------------------- Learn more about what you can do with geo: * [Continents](https://docs.openalex.org/api-entities/geo/continents) * [Regions](https://docs.openalex.org/api-entities/geo/regions) [PreviousGroup awards](https://docs.openalex.org/api-entities/awards/group-awards) [NextContinents](https://docs.openalex.org/api-entities/geo/continents) Last updated 22 days ago --- # Funders | OpenAlex technical documentation Funders are organizations that fund research. OpenAlex indexes about 32,000 funders. Funder data comes from Crossref, and is enhanced with data from Wikidata and ROR. * Get a list of OpenAlex funders: [`https://api.openalex.org/funders`](https://api.openalex.org/funders) Funders are connected to works through [grants.](https://docs.openalex.org/api-entities/works/work-object#grants) [](https://docs.openalex.org/api-entities/funders#whats-next) What's next ------------------------------------------------------------------------------ Learn more about what you can do with funders: * [The Funder object](https://docs.openalex.org/api-entities/funders/funder-object) * [Get a single funder](https://docs.openalex.org/api-entities/funders/get-a-single-funder) * [Get lists of funders](https://docs.openalex.org/api-entities/funders/get-lists-of-funders) * [Filter funders](https://docs.openalex.org/api-entities/funders/filter-funders) * [Search funders](https://docs.openalex.org/api-entities/funders/search-funders) * [Group funders](https://docs.openalex.org/api-entities/funders/group-funders) [PreviousGroup publishers](https://docs.openalex.org/api-entities/publishers/group-publishers) [NextFunder object](https://docs.openalex.org/api-entities/funders/funder-object) Last updated 22 days ago --- # Get a single topic | OpenAlex technical documentation It's easy to get a topic from the API with: `/topics/`. Here's an example: * Get the topic with the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) `C71924100`: [`https://api.openalex.org/topics/T11636`](https://api.openalex.org/topics/T11636) That will return a [`Topic`](https://docs.openalex.org/api-entities/topics/topic-object) object, describing everything OpenAlex knows about the topic with that ID: Copy { "id": "https://openalex.org/T11636", "display_name": "Artificial Intelligence in Medicine", // other fields removed for brevity } You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . ### [](https://docs.openalex.org/api-entities/topics/get-a-single-topic#select-fields) Select fields You can use `select` to limit the fields that are returned in a topic object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` for a topic object [`https://api.openalex.org/topics/T11636?select=id,display\_name`](https://api.openalex.org/topics/T11636?select=id,display_name) [PreviousTopic object](https://docs.openalex.org/api-entities/topics/topic-object) [NextGet lists of topics](https://docs.openalex.org/api-entities/topics/get-lists-of-topics) Last updated 21 days ago --- # Group topics | OpenAlex technical documentation You can group topics with the `group_by` parameter: * Get counts of topics by [`domain`](https://docs.openalex.org/api-entities/topics/topic-object#domain) : [`https://api.openalex.org/topics?group_by=domain.id`](https://api.openalex.org/topics?group_by=domain.id) Or you can group using one the attributes below. It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. ### [](https://docs.openalex.org/api-entities/topics/group-topics#topics-group_by-attributes) Topics group\_by attributes * [`cited_by_count`](https://docs.openalex.org/api-entities/topics/topic-object#cited_by_count) * [`domain.id`](https://docs.openalex.org/api-entities/topics/topic-object#domain) * [`field.id`](https://docs.openalex.org/api-entities/topics/topic-object#field) * [`subfield.id`](https://docs.openalex.org/api-entities/topics/topic-object#subfield) * [`works_count`](https://docs.openalex.org/api-entities/topics/topic-object#works_count) [PreviousSearch topics](https://docs.openalex.org/api-entities/topics/search-topics) [NextKeywords](https://docs.openalex.org/api-entities/keywords) Last updated 22 days ago --- # Get a single institution | OpenAlex technical documentation It's easy to get an institution from from the API with: `/institutions/`. Here's an example: * Get the institution with the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) `I27837315`: [https://api.openalex.org/institutions/I27837315](https://api.openalex.org/institutions/I27837315) That will return an [`Institution`](https://docs.openalex.org/api-entities/institutions/institution-object) object, describing everything OpenAlex knows about the institution with that ID: Copy { "id": "https://openalex.org/I27837315", "ror": "https://ror.org/00jmfr291", "display_name": "University of Michigan–Ann Arbor", "country_code": "US", "type": "education", // other fields removed for brevity } You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . ### [](https://docs.openalex.org/api-entities/institutions/get-a-single-institution#external-ids) External IDs You can look up institutions using external IDs such as a [ROR ID](https://ror.org/) : * Get the institution with ROR ID `https://ror.org/00cvxb145`: [https://api.openalex.org/institutions/ror:https://ror.org/00cvxb145](https://api.openalex.org/institutions/ror:https://ror.org/00cvxb145) Available external IDs for institutions are: External ID URN ROR `ror` Microsoft Academic Graph (MAG) `mag` Wikidata `wikidata` ### [](https://docs.openalex.org/api-entities/institutions/get-a-single-institution#select-fields) Select fields You can use `select` to limit the fields that are returned in an institution object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` for an institution object [https://api.openalex.org/institutions/I27837315?select=id,display\_name](https://api.openalex.org/institutions/I27837315?select=id,display_name) [PreviousInstitution object](https://docs.openalex.org/api-entities/institutions/institution-object) [NextGet lists of institutions](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions) Last updated 22 days ago * [External IDs](https://docs.openalex.org/api-entities/institutions/get-a-single-institution#external-ids) * [Select fields](https://docs.openalex.org/api-entities/institutions/get-a-single-institution#select-fields) --- # Filter topics | OpenAlex technical documentation You can filter topics with the `filter` parameter: * Get topics that are in the subfield "Epidemiology" (id: 2713) [`https://api.openalex.org/topics?filter=subfield.id:2713`](https://api.openalex.org/topics?filter=subfield.id:2713) It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query ### [](https://docs.openalex.org/api-entities/topics/filter-topics#topics-attribute-filters) `/topics` attribute filters You can filter using these attributes of the [`Topic`](https://docs.openalex.org/api-entities/topics/topic-object) object (click each one to view their documentation on the `Topic` object page): * [`cited_by_count`](https://docs.openalex.org/api-entities/topics/topic-object#cited_by_count) * [`domain.id`](https://docs.openalex.org/api-entities/topics/topic-object#domain) * [`field.id`](https://docs.openalex.org/api-entities/topics/topic-object#field) * [`ids.openalex`](https://docs.openalex.org/api-entities/topics/topic-object#ids) (alias: `openalex`) * [`subfield.id`](https://docs.openalex.org/api-entities/topics/topic-object#subfield) * [`works_count`](https://docs.openalex.org/api-entities/topics/topic-object#works_count) ### [](https://docs.openalex.org/api-entities/topics/filter-topics#topics-convenience-filters) `/topics` convenience filters These filters aren't attributes of the [`Topic`](https://docs.openalex.org/api-entities/topics/topic-object) object, but they're included to address some common use cases: #### [](https://docs.openalex.org/api-entities/topics/filter-topics#default.search) `default.search` Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/topics/search-topics#search-topics) for Topics. #### [](https://docs.openalex.org/api-entities/topics/filter-topics#display_name.search) `display_name.search` Value: a search string Returns: topics with a [`display_name`](https://docs.openalex.org/api-entities/topics/topic-object#display_name) containing the given string; see the [search page](https://docs.openalex.org/api-entities/topics/search-topics#search-a-specific-field) for details. * Get topics with `display_name` containing "artificial" and "intelligence": [`https://api.openalex.org/topics?filter=display_name.search:artificial+intelligence`](https://api.openalex.org/topics?filter=display_name.search:artificial+intelligence) In most cases, you should use the [`search` parameter](https://docs.openalex.org/api-entities/topics/search-topics#topics-full-search) instead of this filter because it uses a better search algorithm. [PreviousGet lists of topics](https://docs.openalex.org/api-entities/topics/get-lists-of-topics) [NextSearch topics](https://docs.openalex.org/api-entities/topics/search-topics) Last updated 22 days ago * [/topics attribute filters](https://docs.openalex.org/api-entities/topics/filter-topics#topics-attribute-filters) * [/topics convenience filters](https://docs.openalex.org/api-entities/topics/filter-topics#topics-convenience-filters) --- # Group publishers | OpenAlex technical documentation You can group publishers with the `group_by` parameter: * Get counts of publishers by [`country_codes`](https://docs.openalex.org/api-entities/publishers/publisher-object#country_codes) : [`https://api.openalex.org/publishers?group\_by=country\_codes`](https://api.openalex.org/publishers?group_by=country_codes) Or you can group using one the attributes below. It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. ### [](https://docs.openalex.org/api-entities/publishers/group-publishers#publishers-group_by-attributes) `/publishers` group\_by attributes * [`country_codes`](https://docs.openalex.org/api-entities/publishers/publisher-object#country_codes) * [`hierarchy_level`](https://docs.openalex.org/api-entities/publishers/publisher-object#hierarchy_level) * [`lineage`](https://docs.openalex.org/api-entities/publishers/publisher-object#lineage) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/publishers/publisher-object#summary_stats) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/publishers/publisher-object#summary_stats) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/publishers/publisher-object#summary_stats) [PreviousSearch publishers](https://docs.openalex.org/api-entities/publishers/search-publishers) [NextFunders](https://docs.openalex.org/api-entities/funders) Last updated 22 days ago --- # Get lists of publishers | OpenAlex technical documentation You can get lists of publishers: * Get _all_ publishers in OpenAlex [https://api.openalex.org/publishers](https://api.openalex.org/publishers) Which returns a response like this: Copy { "meta": { "count": 7207, "db_response_time_ms": 26, "page": 1, "per_page": 25 }, "results": [\ {\ "id": "https://openalex.org/P4310311775",\ "display_name": "RELX Group",\ // more fields (removed to save space)\ },\ {\ "id": "https://openalex.org/P4310320990",\ "display_name": "Elsevier BV",\ // more fields (removed to save space)\ },\ // more results (removed to save space)\ ], "group_by": [] } [](https://docs.openalex.org/api-entities/publishers/get-lists-of-publishers#page-and-sort-publishers) Page and sort publishers ------------------------------------------------------------------------------------------------------------------------------------ By default we return 25 results per page. You can change this default and [page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) through publishers with the `per-page` and `page` parameters: * Get the second page of publishers results, with 50 results returned per page [https://api.openalex.org/publishers?per-page=50&page=2](https://api.openalex.org/publishers?per-page=50&page=2) You also can [sort results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) with the `sort` parameter: * Sort publishers by display name, descending [https://api.openalex.org/publishers?sort=display\_name:desc](https://api.openalex.org/publishers?sort=display_name:desc) Continue on to learn how you can [filter](https://docs.openalex.org/api-entities/publishers/filter-publishers) and [search](https://docs.openalex.org/api-entities/publishers/search-publishers) lists of publishers. [](https://docs.openalex.org/api-entities/publishers/get-lists-of-publishers#sample-publishers) Sample publishers ---------------------------------------------------------------------------------------------------------------------- You can use `sample` to get a random batch of publishers. Read more about sampling and how to add a `seed` value [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) . * Get 10 random publishers [https://api.openalex.org/publishers?sample=10](https://api.openalex.org/publishers?sample=10) [](https://docs.openalex.org/api-entities/publishers/get-lists-of-publishers#select-fields) Select fields -------------------------------------------------------------------------------------------------------------- You can use `select` to limit the fields that are returned in a list of publishers. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id`, `display_name`, and `alternate_titles` within publishers results [https://api.openalex.org/publishers?select=id,display\_name,alternate\_titles](https://api.openalex.org/publishers?select=id,display_name,alternate_titles) [PreviousGet a single publisher](https://docs.openalex.org/api-entities/publishers/get-a-single-publisher) [NextFilter publishers](https://docs.openalex.org/api-entities/publishers/filter-publishers) Last updated 22 days ago * [Page and sort publishers](https://docs.openalex.org/api-entities/publishers/get-lists-of-publishers#page-and-sort-publishers) * [Sample publishers](https://docs.openalex.org/api-entities/publishers/get-lists-of-publishers#sample-publishers) * [Select fields](https://docs.openalex.org/api-entities/publishers/get-lists-of-publishers#select-fields) --- # Group institutions | OpenAlex technical documentation You can group institutions with the `group_by` parameter: * Get counts of institutions by country code: [https://api.openalex.org/institutions?group\_by=country\_code](https://api.openalex.org/institutions?group_by=country_code) Or you can group using one the attributes below. It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. ### [](https://docs.openalex.org/api-entities/institutions/group-institutions#institutions-group_by-attributes) `/institutions` group\_by attributes * [`cited_by_count`](https://docs.openalex.org/api-entities/institutions/institution-object#cited_by_count) * [`continent`](https://docs.openalex.org/api-entities/institutions/filter-institutions#continent) * [`country_code`](https://docs.openalex.org/api-entities/institutions/institution-object#country_code) * [`has_ror`](https://docs.openalex.org/api-entities/institutions/filter-institutions#has_ror) * [`is_global_south`](https://docs.openalex.org/api-entities/institutions/filter-institutions#is_global_south) * [`is_super_system`](https://docs.openalex.org/api-entities/institutions/institution-object#is_super_system) * [`lineage`](https://docs.openalex.org/api-entities/institutions/institution-object#lineage) * [`repositories.host_organization`](https://docs.openalex.org/api-entities/institutions/institution-object#repositories) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/institutions/institution-object#summary_stats) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/institutions/institution-object#summary_stats) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/institutions/institution-object#summary_stats) * [`type`](https://docs.openalex.org/api-entities/institutions/institution-object#type) * [`works_count`](https://docs.openalex.org/api-entities/institutions/institution-object#works_count) [PreviousSearch institutions](https://docs.openalex.org/api-entities/institutions/search-institutions) [NextTopics](https://docs.openalex.org/api-entities/topics) Last updated 22 days ago --- # Group funders | OpenAlex technical documentation You can group funders with the `group_by` parameter: * Get counts of funders by [`country_code`](https://docs.openalex.org/api-entities/funders/funder-object#country_code) : [`https://api.openalex.org/funders?group_by=country_code`](https://api.openalex.org/funders?group_by=country_code) Or you can group using one the attributes below. It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. ### [](https://docs.openalex.org/api-entities/funders/group-funders#funders-group_by-attributes) `/funders` group\_by attributes * [`cited_by_count`](https://docs.openalex.org/api-entities/funders/funder-object#cited_by_count) * [`continent`](https://docs.openalex.org/api-entities/funders/filter-funders#continent) * [`country_code`](https://docs.openalex.org/api-entities/funders/funder-object#country_code) * [`grants_count`](https://docs.openalex.org/api-entities/funders/funder-object#grants_count) * [`is_global_south`](https://docs.openalex.org/api-entities/funders/filter-funders#is_global_south) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/funders/funder-object#summary_stats) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/funders/funder-object#summary_stats) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/funders/funder-object#summary_stats) * [`works_count`](https://docs.openalex.org/api-entities/funders/funder-object#works_count) [PreviousSearch funders](https://docs.openalex.org/api-entities/funders/search-funders) [NextAwards](https://docs.openalex.org/api-entities/awards) Last updated 22 days ago --- # Search topics | OpenAlex technical documentation The best way to search for topics is to use the `search` query parameter, which searches the [`display_name`](https://docs.openalex.org/api-entities/topics/topic-object#display_name) , [`description`](https://docs.openalex.org/api-entities/topics/topic-object#description) , and [`keyword`](https://docs.openalex.org/api-entities/topics/topic-object#keywords) fields. Example: * Search topics' `display_name` and `description` for "artificial intelligence": [https://api.openalex.org/topics?search=artificial intelligence](https://api.openalex.org/topics?search=artificial%20intelligence) You can read more about search [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. [](https://docs.openalex.org/api-entities/topics/search-topics#search-a-specific-field) Search a specific field -------------------------------------------------------------------------------------------------------------------- You can also use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , allowing you to fine-tune the fields you're searching over. To do this, you append `.search` to the end of the property you are filtering for: * Get topics with "medical" in the `display_name`: [https://api.openalex.org/topics?filter=display\_name.search:medical](https://api.openalex.org/topics?filter=display_name.search:medical) The following fields can be searched as a filter within topics: Search filter Field that is searched [`display_name.search`](https://docs.openalex.org/api-entities/topics/filter-topics#display_name.search) [`display_name`](https://docs.openalex.org/api-entities/topics/topic-object#display_name) [`description.search`](https://docs.openalex.org/api-entities/topics/filter-topics#description.search) [`description`](https://docs.openalex.org/api-entities/topics/topic-object#description) [`keywords.search`](https://docs.openalex.org/api-entities/topics/filter-topics#keywords.search) [`keywords`](https://docs.openalex.org/api-entities/topics/topic-object#keywords) You can also use the filter `default.search`, which works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/topics/search-topics#search-topics) . [PreviousFilter topics](https://docs.openalex.org/api-entities/topics/filter-topics) [NextGroup topics](https://docs.openalex.org/api-entities/topics/group-topics) Last updated 22 days ago --- # Get lists of topics | OpenAlex technical documentation You can get lists of topics: * Get _all_ topics in OpenAlex [`https://api.openalex.org/topics`](https://api.openalex.org/topics) Which returns a response like this: Copy { "meta": { "count": 4516, "db_response_time_ms": 10, "page": 1, "per_page": 25, "groups_count": null }, "results": [\ {\ "id": "https://openalex.org/T11475",\ "display_name": "Territorial Governance and Environmental Participation",\ // more fields (removed to save space)\ },\ {\ "id": "https://openalex.org/T13445",\ "display_name": "American Political Thought and History",\ // more fields (removed to save space)\ },\ // more results (removed to save space)\ ], "group_by": [] } [](https://docs.openalex.org/api-entities/topics/get-lists-of-topics#page-and-sort-topics) Page and sort topics -------------------------------------------------------------------------------------------------------------------- By default we return 25 results per page. You can change this default and [page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) through topics with the `per-page` and `page` parameters: * Get the second page of topics results, with 50 results returned per page [`https://api.openalex.org/topics?per-page=50\&page=2`](https://api.openalex.org/topics?per-page=50&page=2) You also can [sort results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) with the `sort` parameter: * Sort topics by cited by count, descending [`https://api.openalex.org/topics?sort=cited\_by\_count:desc`](https://api.openalex.org/topics?sort=cited_by_count:desc) Continue on to learn how you can [filter](https://docs.openalex.org/api-entities/topics/filter-topics) and [search](https://docs.openalex.org/api-entities/topics/search-topics) lists of topics. [](https://docs.openalex.org/api-entities/topics/get-lists-of-topics#sample-topics) Sample topics ------------------------------------------------------------------------------------------------------ You can use `sample` to get a random batch of topics. Read more about sampling and how to add a `seed` value [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) . * Get 10 random topics [`https://api.openalex.org/topics?sample=10`](https://api.openalex.org/topics?sample=10) [](https://docs.openalex.org/api-entities/topics/get-lists-of-topics#select-fields) Select fields ------------------------------------------------------------------------------------------------------ You can use `select` to limit the fields that are returned in a list of topics. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id`, `display_name`, and `description` within topics results [`https://api.openalex.org/topics?select=id,display\_name,description`](https://api.openalex.org/topics?select=id,display_name,description) [PreviousGet a single topic](https://docs.openalex.org/api-entities/topics/get-a-single-topic) [NextFilter topics](https://docs.openalex.org/api-entities/topics/filter-topics) Last updated 22 days ago * [Page and sort topics](https://docs.openalex.org/api-entities/topics/get-lists-of-topics#page-and-sort-topics) * [Sample topics](https://docs.openalex.org/api-entities/topics/get-lists-of-topics#sample-topics) * [Select fields](https://docs.openalex.org/api-entities/topics/get-lists-of-topics#select-fields) --- # Continents | OpenAlex technical documentation Countries are mapped to continents using data from the [United Nations Statistics Division](https://unstats.un.org/unsd/methodology/m49/) . You can see the actual mapping used by the API [here](https://github.com/ourresearch/openalex-elastic-api/blob/master/country_list.py) . #### [](https://docs.openalex.org/api-entities/geo/continents#filter-by-continent) **Filter by continent** There are three ways to use continent filters: Endpoint Format Authors `/authors?filter=last_known_institution.continent:` Institutions `/institutions?filter=continent:` Works `/works?filter=institutions.continent:` Available values for the `` filter are: Continent Filter Value Canonical ID Africa `africa` [Q15](https://www.wikidata.org/wiki/Q15) Antarctica `antarctica` [Q51](https://www.wikidata.org/wiki/Q51) Asia `asia` [Q48](https://www.wikidata.org/wiki/Q48) Europe `europe` [Q46](https://www.wikidata.org/wiki/Q46) North America `north_america` [Q49](https://www.wikidata.org/wiki/Q49) Oceania `oceania` [Q55643](https://www.wikidata.org/wiki/Q55643) South America `south_america` [Q18](https://www.wikidata.org/wiki/Q18) #### [](https://docs.openalex.org/api-entities/geo/continents#group-by-continent) **Group by continent** You can group by continent. * Group institutions by continent [`https://api.openalex.org/institutions?group-by=continent`](https://api.openalex.org/institutions?group-by=continent) Response: Groups are available in these endpoints: Endpoint Format Authors `/authors?group-by=last_known_institution.continent` Institutions `/institutions?group-by=continent` Works `/works?group-by=institutions.continent` [PreviousGeo](https://docs.openalex.org/api-entities/geo) [NextRegions](https://docs.openalex.org/api-entities/geo/regions) Last updated 21 days ago Copy { key: "Q46", key_display_name: "Europe", count: 41382 }, { key: "Q49", key_display_name: "North America", count: 37458 }, { key: "Q48", key_display_name: "Asia", count: 20432 }... --- # Regions | OpenAlex technical documentation ### [](https://docs.openalex.org/api-entities/geo/regions#global-south) **Global South** The Global South is a term used to identify regions within Latin America, Asia, Africa, and Oceania. Our source for this group of countries is the [United Nations Finance Center for South-South Cooperation](http://www.fc-ssc.org/en/partnership_program/south_south_countries) . #### [](https://docs.openalex.org/api-entities/geo/regions#filter-by-global-south) Filter by Global South You can filter Global South countries by using the boolean filter `is_global_south` in the following endpoints: Endpoint Format Authors `/authors?filter=last_known_institution.is_global_south:` Institutions `/institutions?filter=is_global_south:` Works `/works?filter=institutions.is_global_south:` #### [](https://docs.openalex.org/api-entities/geo/regions#group-by-global-south) Group by Global South You can also group by the Global South: Endpoint Format Authors `/authors?group-by=last_known_institution.is_global_south` Institutions `/institutions?group-by=is_global_south` Works `/works?group-by=institutions.is_global_south` ### [](https://docs.openalex.org/api-entities/geo/regions#tips-and-tricks) Tips & Tricks To see country-by-country details for a geographic region, filter by region, then group by `country_code`. * Get number of authors with last known institution in the Global South, by country [https://api.openalex.org/authors?filter=last\_known\_institution.is\_global\_south:true&group-by=last\_known\_institution.country\_code](https://api.openalex.org/authors?filter=last_known_institution.is_global_south:true&group-by=last_known_institution.country_code) Response: [PreviousContinents](https://docs.openalex.org/api-entities/geo/continents) [NextConcepts](https://docs.openalex.org/api-entities/concepts) Last updated 22 days ago * [Global South](https://docs.openalex.org/api-entities/geo/regions#global-south) * [Tips & Tricks](https://docs.openalex.org/api-entities/geo/regions#tips-and-tricks) Copy // all countries are in the Global South { key: "CN", key_display_name: "China", count: 13926441 }, { key: "IN", key_display_name: "India", count: 2632721 }, { key: "BR", key_display_name: "Brazil", count: 2089957 }... --- # Filter publishers | OpenAlex technical documentation You can filter publishers with the `filter` parameter: * Get publishers that are hierarchy level 0 [`https://api.openalex.org/publishers?filter=hierarchy\_level:0`](https://api.openalex.org/publishers?filter=hierarchy_level:0) It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query ### [](https://docs.openalex.org/api-entities/publishers/filter-publishers#publishers-attribute-filters) `/publishers` attribute filters You can filter using these attributes of the `Publisher` entity object (click each one to view their documentation on the [`Publisher`](https://docs.openalex.org/api-entities/publishers/publisher-object) object page): * [`cited_by_count`](https://docs.openalex.org/api-entities/publishers/publisher-object#cited_by_count) * [`country_codes`](https://docs.openalex.org/api-entities/publishers/publisher-object#country_codes) * [`hierarchy_level`](https://docs.openalex.org/api-entities/publishers/publisher-object#hierarchy_level) * [`ids.openalex`](https://docs.openalex.org/api-entities/publishers/publisher-object#ids) (alias: `openalex`) * [`ids.ror`](https://docs.openalex.org/api-entities/publishers/publisher-object#ids) (alias: `ror`) * [`ids.wikidata`](https://docs.openalex.org/api-entities/publishers/publisher-object#ids) (alias: `wikidata`) * [`lineage`](https://docs.openalex.org/api-entities/publishers/publisher-object#lineage) — Use this with a publisher ID to find that publisher and all of its children * [`parent_publisher`](https://docs.openalex.org/api-entities/publishers/publisher-object#parent_publisher) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/publishers/publisher-object#summary_stats) (accepts float, null, !null, can use range queries such as < >) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/publishers/publisher-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/publishers/publisher-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`works_count`](https://docs.openalex.org/api-entities/publishers/publisher-object#works_count) ### [](https://docs.openalex.org/api-entities/publishers/filter-publishers#publishers-convenience-filters) `/publishers` convenience filters These filters aren't attributes of the [`Publisher`](https://docs.openalex.org/api-entities/publishers/publisher-object) object, but they're included to address some common use cases: #### [](https://docs.openalex.org/api-entities/publishers/filter-publishers#continent) `continent` Value: a String with a valid [continent filter](https://docs.openalex.org/api-entities/geo/continents#filter-by-continent) Returns: publishers that are located in the chosen continent. * Get publishers that are located in South America [https://api.openalex.org/publishers?filter=continent:south\_america](https://api.openalex.org/publishers?filter=continent:south_america) #### [](https://docs.openalex.org/api-entities/publishers/filter-publishers#default.search) `default.search` Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/publishers/search-publishers#search-publishers) for Publishers. #### [](https://docs.openalex.org/api-entities/publishers/filter-publishers#display_name.search) `display_name.search` Value: a search string Returns: publishers with a [`display_name`](https://docs.openalex.org/api-entities/publishers/publisher-object#display_name) containing the given string; see the [search page](https://docs.openalex.org/api-entities/publishers/search-publishers#search-a-specific-field) for details. * Get publishers with names containing "elsevier": [`https://api.openalex.org/publishers?filter=display_name.search:elsevier`](https://api.openalex.org/publishers?filter=display_name.search:elsevier) \`\` {% hint style="info" %} In most cases, you should use the \[\`\ \ search\` parameter\](search-publishers.md) instead of this filter because it uses a better search algorithm. [PreviousGet lists of publishers](https://docs.openalex.org/api-entities/publishers/get-lists-of-publishers) [NextSearch publishers](https://docs.openalex.org/api-entities/publishers/search-publishers) Last updated 22 days ago * [/publishers attribute filters](https://docs.openalex.org/api-entities/publishers/filter-publishers#publishers-attribute-filters) * [/publishers convenience filters](https://docs.openalex.org/api-entities/publishers/filter-publishers#publishers-convenience-filters) --- # Awards | OpenAlex technical documentation Awards are grants or funding awards that support research. OpenAlex indexes awards from multiple sources including Crossref grant metadata and other funding databases. * Get a list of OpenAlex awards: [`https://api.openalex.org/awards`](https://api.openalex.org/awards) Awards are connected to works through the [`awards`](https://docs.openalex.org/api-entities/works/work-object#awards) property, and to funders through the [`funder`](https://docs.openalex.org/api-entities/awards/award-object#funder) property. The `awards` entity, along with the [`funders`](https://docs.openalex.org/api-entities/funders) property on works, replaces the older `grants` property which has been removed. These new entities provide much more comprehensive funding data. [](https://docs.openalex.org/api-entities/awards#whats-next) What's next ----------------------------------------------------------------------------- Learn more about what you can do with awards: * [The Award object](https://docs.openalex.org/api-entities/awards/award-object) * [Get a single award](https://docs.openalex.org/api-entities/awards/get-a-single-award) * [Get lists of awards](https://docs.openalex.org/api-entities/awards/get-lists-of-awards) * [Filter awards](https://docs.openalex.org/api-entities/awards/filter-awards) * [Search awards](https://docs.openalex.org/api-entities/awards/search-awards) * [Group awards](https://docs.openalex.org/api-entities/awards/group-awards) [PreviousGroup funders](https://docs.openalex.org/api-entities/funders/group-funders) [NextAward object](https://docs.openalex.org/api-entities/awards/award-object) Last updated 22 days ago --- # Aboutness endpoint (/text) | OpenAlex technical documentation You can use the `/text` API endpoint to tag your own free text with OpenAlex's "aboutness" assignments—topics, keywords, and concepts. Accepts a `title` and optional `abstract` in the GET params or as a POST request. The results are straight from the model, with 0 values truncated. #### [](https://docs.openalex.org/api-entities/aboutness-endpoint-text#examples) Examples * Get OpenAlex [Keywords](https://docs.openalex.org/api-entities/keywords) for your text [`https://api.openalex.org/text/keywords?title=type%201%20diabetes%20research%20for%20children`](https://api.openalex.org/text/keywords?title=type%201%20diabetes%20research%20for%20children) * Get OpenAlex [Topics](https://docs.openalex.org/api-entities/topics) for your text [`https://api.openalex.org/text/topics?title=type%201%20diabetes%20research%20for%20children`](https://api.openalex.org/text/topics?title=type%201%20diabetes%20research%20for%20children) * Get OpenAlex [Concepts](https://docs.openalex.org/api-entities/concepts) for your text [`https://api.openalex.org/text/concepts?title=type%201%20diabetes%20research%20for%20children`](https://api.openalex.org/text/concepts?title=type%201%20diabetes%20research%20for%20children) * Get all of the above in one request [`https://api.openalex.org/text?title=type%201%20diabetes%20research%20for%20children`](https://api.openalex.org/text?title=type%201%20diabetes%20research%20for%20children) Example response for that last one: Copy { meta: { keywords_count: 5, topics_count: 3, concepts_count: 3 }, keywords: [\ id: "https://openalex.org/keywords/type-1-diabetes",\ display_name: "Type 1 Diabetes",\ score: 0.677\ ], ... primary_topic: { id: "https://openalex.org/T10560", display_name: "Management of Diabetes Mellitus and Hypoglycemia", score: 0.995 // more information about the primary topic, removed for brevity }, topics: [\ // list of topic objects with scores\ ], concepts: [\ // list of concept objects with scores\ ] } Queries are limited to between 20 and 2000 characters. The endpoints are rate limited to 1 per second and 1000 requests per day. [PreviousGroup concepts](https://docs.openalex.org/api-entities/concepts/group-concepts) [NextAPI Overview](https://docs.openalex.org/how-to-use-the-api/api-overview) Last updated 22 days ago --- # Select fields | OpenAlex technical documentation You can use `select` to choose top-level fields you want to see in a result. * Display `id` and `display_name` for a work [`https://api.openalex.org/works/W2138270253?select=id,display_name`](https://api.openalex.org/works/W2138270253?select=id,display_name) Copy { id: "https://openalex.org/W2138270253", display_name: "DNA sequencing with chain-terminating inhibitors" } Read more about this feature [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . [PreviousRandom result](https://docs.openalex.org/how-to-use-the-api/get-single-entities/random-result) [NextGet lists of entities](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities) Last updated 22 days ago --- # Search publishers | OpenAlex technical documentation The best way to search for publishers is to use the `search` query parameter, which searches the [`display_name`](https://docs.openalex.org/api-entities/publishers/publisher-object#display_name) and [`alternate_titles`](https://docs.openalex.org/api-entities/publishers/publisher-object#alternate_titles) fields. Example: * Search publishers' `display_name` and `alternate_titles` for "springer": [https://api.openalex.org/publishers?search=springer](https://api.openalex.org/publishers?search=springer) You can read more about search [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. [](https://docs.openalex.org/api-entities/publishers/search-publishers#search-a-specific-field) Search a specific field ---------------------------------------------------------------------------------------------------------------------------- You can also use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , allowing you to fine-tune the fields you're searching over. To do this, you append `.search` to the end of the property you are filtering for: * Get publishers with "elsevier" in the `display_name`: https://api.openalex.org/publishers?filter=display\_name.search:elsevier The following field can be searched as a filter within publishers: Search filter Field that is searched [`display_name.search`](https://docs.openalex.org/api-entities/publishers/filter-publishers#display_name.search) [`display_name`](https://docs.openalex.org/api-entities/publishers/publisher-object#display_name) You can also use the filter `default.search`, which works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/publishers/search-publishers#search-publishers) . [](https://docs.openalex.org/api-entities/publishers/search-publishers#autocomplete-publishers) Autocomplete publishers ---------------------------------------------------------------------------------------------------------------------------- You can autocomplete publishers to create a very fast type-ahead style search function: * Autocomplete publishers with "els" in the `display_name`: [https://api.openalex.org/autocomplete/publishers?q=els](https://api.openalex.org/autocomplete/publishers?q=els) This returns a list of publishers: Copy { "results": [\ {\ "id": "https://openalex.org/P4310320990",\ "display_name": "Elsevier BV",\ "hint": null,\ "cited_by_count": 407508754,\ "works_count": 20311868,\ "entity_type": "publisher",\ "external_id": "https://www.wikidata.org/entity/Q746413"\ },\ ...\ ] } Read more in the [autocomplete page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) in the API guide. [PreviousFilter publishers](https://docs.openalex.org/api-entities/publishers/filter-publishers) [NextGroup publishers](https://docs.openalex.org/api-entities/publishers/group-publishers) Last updated 22 days ago * [Search a specific field](https://docs.openalex.org/api-entities/publishers/search-publishers#search-a-specific-field) * [Autocomplete publishers](https://docs.openalex.org/api-entities/publishers/search-publishers#autocomplete-publishers) --- # Get a single funder | OpenAlex technical documentation It's easy to get a funder from from the API with: `/funders/`. Here's an example: * Get the funder with the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) `F4320332161`: [https://api.openalex.org/funders/F4320332161](https://api.openalex.org/funders/F4320332161) That will return a [`Funder`](https://docs.openalex.org/api-entities/funders/funder-object) object, describing everything OpenAlex knows about the funder with that ID: Copy { "id": "https://openalex.org/F4320332161", "display_name": "National Institutes of Health", "alternate_titles": [\ "US National Institutes of Health",\ "Institutos Nacionales de la Salud",\ "NIH"\ ], // other fields removed for brevity } You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . ### [](https://docs.openalex.org/api-entities/funders/get-a-single-funder#external-ids) External IDs You can look up funders using external IDs such as a Wikidata ID: * Get the funder with Wikidata ID Q1479654: [`https://api.openalex.org/funders/wikidata:Q390551`](https://api.openalex.org/funders/wikidata:Q390551) Available external IDs for funders are: External ID URN ROR `ror` Wikidata `wikidata` ### [](https://docs.openalex.org/api-entities/funders/get-a-single-funder#select-fields) Select fields You can use `select` to limit the fields that are returned in a funder object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` for a funder object [`https://api.openalex.org/funders/F4320332161?select=id,display_name`](https://api.openalex.org/funders/F4320332161?select=id,display_name) [PreviousFunder object](https://docs.openalex.org/api-entities/funders/funder-object) [NextGet lists of funders](https://docs.openalex.org/api-entities/funders/get-lists-of-funders) Last updated 22 days ago * [External IDs](https://docs.openalex.org/api-entities/funders/get-a-single-funder#external-ids) * [Select fields](https://docs.openalex.org/api-entities/funders/get-a-single-funder#select-fields) --- # Author object | OpenAlex technical documentation When you use the API to get a [single author](https://docs.openalex.org/api-entities/authors/get-a-single-author) or [lists of authors](https://docs.openalex.org/api-entities/authors/get-lists-of-authors) , this is what's returned. ### [](https://docs.openalex.org/api-entities/authors/author-object#affiliations) `affiliations` _List:_ List of objects, representing the affiliations this author has claimed in their publications. Each object in the list has two properties: * `institution`: a [dehydrated `Institution`](https://docs.openalex.org/api-entities/institutions/institution-object#the-dehydratedinstitution-object) object * `years`: a list of the years in which this author claimed an affiliation with this institution Copy affiliations: [\ {\ institution: {\ id: "https://openalex.org/I201448701",\ ror: "https://ror.org/00cvxb145",\ ...\ },\ years: [2018, 2019, 2020]\ },\ {\ institution: {\ id: "https://openalex.org/I74973139",\ ror: "https://ror.org/05x2bcf33",\ ...\ },\ years: [2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019]\ }\ ] ### [](https://docs.openalex.org/api-entities/authors/author-object#cited_by_count) `cited_by_count` _Integer:_ The total number 📄 [Works](https://docs.openalex.org/api-entities/works/work-object) that cite a work this author has created. ### [](https://docs.openalex.org/api-entities/authors/author-object#counts_by_year) `counts_by_year` _List:_ [`Author.works_count`](https://docs.openalex.org/api-entities/authors/author-object#works_count) and [`Author.cited_by_count`](https://docs.openalex.org/api-entities/authors/author-object#cited_by_count) for each of the last ten years, binned by year. To put it another way: each year, you can see how many works this author published, and how many times they got cited. Any works or citations older than ten years old aren't included. Years with zero works and zero citations have been removed so you will need to add those in if you need them. ### [](https://docs.openalex.org/api-entities/authors/author-object#created_date) `created_date` _String:_ The date this `Author` object was created in the OpenAlex dataset, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. ### [](https://docs.openalex.org/api-entities/authors/author-object#display_name) `display_name` _String:_ The name of the author as a single string. ### [](https://docs.openalex.org/api-entities/authors/author-object#display_name_alternatives) `display_name_alternatives` _List:_ Other ways that we've found this author's name displayed. ### [](https://docs.openalex.org/api-entities/authors/author-object#id) `id` _String:_ The OpenAlex ID for this author. ### [](https://docs.openalex.org/api-entities/authors/author-object#ids) `ids` _Object:_ All the external identifiers that we know about for this author. IDs are expressed as URIs whenever possible. Possible ID types: * `openalex` (_String:_ this author's [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) . Same as [`Author.id`](https://docs.openalex.org/api-entities/authors/author-object#id) ) * `orcid` (_String:_ this author's [ORCID](https://orcid.org/) [ID](https://en.wikipedia.org/wiki/RAS_syndrome) . Same as [`Author.orcid`](https://docs.openalex.org/api-entities/authors/author-object#orcid) ) * `scopus` (_String_: this author's [Scopus author ID](https://utas.libguides.com/ManageID/Scopus) ) * `twitter` (_String:_ this author's Twitter handle) * `wikipedia` (_String_: this author's Wikipedia page) Most authors are missing one or more ID types (either because we don't know the ID, or because it was never assigned). Keys for null IDs are not displayed. ### [](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution-deprecated) `last_known_institution` (deprecated) This field has been deprecated. Its replacement is [`last_known_institutions`](https://docs.openalex.org/api-entities/authors/author-object#last_known_institutions) . ### [](https://docs.openalex.org/api-entities/authors/author-object#last_known_institutions) `last_known_institutions` _List:_ List of Institution objects. This author's last known institutional affiliations. In this context "last known" means that we took all the author's [Works](https://docs.openalex.org/api-entities/works/work-object) , sorted them by publication date, and selected the most recent one. If there is only one affiliated institution for this author for the work, this will be a list of length 1; if there are multiple affiliations, they will all be included in the list. Each item in the list is a [dehydrated `Institution`](https://docs.openalex.org/api-entities/institutions/institution-object#the-dehydratedinstitution-object) object, and you can find more documentation on the [Institution](https://docs.openalex.org/api-entities/institutions/institution-object) page. ### [](https://docs.openalex.org/api-entities/authors/author-object#orcid) `orcid` _String:_ The [ORCID](https://en.wikipedia.org/wiki/ORCID) [ID](https://en.wikipedia.org/wiki/RAS_syndrome) for this author. ORCID is a global and unique ID for authors. This is the [Canonical external ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for authors. Compared to other Canonical IDs, ORCID coverage is relatively low in OpenAlex, because ORCID adoption in the wild has been slow compared with DOI, for example. This is particularly an issue when dealing with older works and authors. ### [](https://docs.openalex.org/api-entities/authors/author-object#summary_stats) `summary_stats` _Object:_ Citation metrics for this author * `2yr_mean_citedness` _Float_: The 2-year mean citedness for this source. Also known as [impact factor](https://en.wikipedia.org/wiki/Impact_factor) . We use the year prior to the current year for the citations (the numerator) and the two years prior to that for the citation-receiving publications (the denominator). * `h_index` _Integer_: The [_h_\-index](https://en.wikipedia.org/wiki/H-index) for this author. * `i10_index` _Integer_: The [i-10 index](https://en.wikipedia.org/wiki/Author-level_metrics#i-10-index) for this author. While the 2-year mean citedness is normally a journal-level metric, it can be calculated for any set of papers, so we include it for authors. ### [](https://docs.openalex.org/api-entities/authors/author-object#updated_date) `updated_date` _String:_ The last time anything in this author object changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. This date is updated for _any change at all_, including increases in various counts. ### [](https://docs.openalex.org/api-entities/authors/author-object#works_api_url) `works_api_url` _String:_ A URL that will get you a list of all this author's works. We express this as an API URL (instead of just listing the works themselves) because sometimes an author's publication list is too long to reasonably fit into a single author object. ### [](https://docs.openalex.org/api-entities/authors/author-object#works_count) `works_count` _Integer:_ The number of 📄 [Works](https://docs.openalex.org/api-entities/works/work-object) this this author has created. This is updated a couple times per day. So the count may be slightly different than what's in works when viewed [like this](https://api.openalex.org/works?filter=author.id:A5023888391) . ### [](https://docs.openalex.org/api-entities/authors/author-object#x_concepts) `x_concepts` `x_concepts` will be deprecated and removed soon. We will be replacing this functionality with [`Topics`](https://docs.openalex.org/api-entities/topics) instead. _List:_ The concepts most frequently applied to works created by this author. Each is represented as a [dehydrated `Concept`](https://docs.openalex.org/api-entities/concepts/concept-object#the-dehydratedconcept-object) object, with one additional attribute: * `score` (_Float_): The strength of association between this author and the listed concept, from 0-100. [](https://docs.openalex.org/api-entities/authors/author-object#the-dehydratedauthor-object) The Dehydrated`Author` object ------------------------------------------------------------------------------------------------------------------------------- The `DehydratedAuthor` is stripped-down [`Author`](https://docs.openalex.org/api-entities/authors/author-object#the-author-object) object, with most of its properties removed to save weight. Its only remaining properties are: * [`id`](https://docs.openalex.org/api-entities/authors/author-object#id) * [`display_name`](https://docs.openalex.org/api-entities/authors/author-object#display_name) * [`orcid`](https://docs.openalex.org/api-entities/authors/author-object#orcid) [PreviousAuthors](https://docs.openalex.org/api-entities/authors) [NextGet a single author](https://docs.openalex.org/api-entities/authors/get-a-single-author) Last updated 22 days ago * [affiliations](https://docs.openalex.org/api-entities/authors/author-object#affiliations) * [cited\_by\_count](https://docs.openalex.org/api-entities/authors/author-object#cited_by_count) * [counts\_by\_year](https://docs.openalex.org/api-entities/authors/author-object#counts_by_year) * [created\_date](https://docs.openalex.org/api-entities/authors/author-object#created_date) * [display\_name](https://docs.openalex.org/api-entities/authors/author-object#display_name) * [display\_name\_alternatives](https://docs.openalex.org/api-entities/authors/author-object#display_name_alternatives) * [id](https://docs.openalex.org/api-entities/authors/author-object#id) * [ids](https://docs.openalex.org/api-entities/authors/author-object#ids) * [last\_known\_institution (deprecated)](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution-deprecated) * [last\_known\_institutions](https://docs.openalex.org/api-entities/authors/author-object#last_known_institutions) * [orcid](https://docs.openalex.org/api-entities/authors/author-object#orcid) * [summary\_stats](https://docs.openalex.org/api-entities/authors/author-object#summary_stats) * [updated\_date](https://docs.openalex.org/api-entities/authors/author-object#updated_date) * [works\_api\_url](https://docs.openalex.org/api-entities/authors/author-object#works_api_url) * [works\_count](https://docs.openalex.org/api-entities/authors/author-object#works_count) * [x\_concepts](https://docs.openalex.org/api-entities/authors/author-object#x_concepts) * [The DehydratedAuthor object](https://docs.openalex.org/api-entities/authors/author-object#the-dehydratedauthor-object) Copy cited_by_count: 38 Copy counts_by_year: [\ {\ year: 2022,\ works_count: 0,\ cited_by_count: 8\ },\ {\ year: 2021,\ works_count: 1,\ cited_by_count: 252\ },\ ...\ {\ year: 2012,\ works_count: 7,\ cited_by_count: 79\ }\ ] Copy created_date: "2017-08-08" Copy display_name: "Jason Priem" Copy display_name_alternatives: [\ "Jason R Priem"\ ] Copy id: "https://openalex.org/A5023888391" Copy ids: { openalex: "https://openalex.org/A5023888391", orcid: "https://orcid.org/0000-0001-6187-6610", scopus: "http://www.scopus.com/inward/authorDetails.url?authorID=36455008000&partnerID=MN8TOARS", }, Copy last_known_institutions: [{\ id: "https://openalex.org/I4200000001",\ ror: "https://ror.org/02nr0ka47",\ display_name: "OurResearch",\ country_code: "CA",\ type: "nonprofit",\ lineage: ["https://openalex.org/I4200000001"]\ }], Copy orcid: "https://orcid.org/0000-0001-6187-6610" Copy summary_stats: { 2yr_mean_citedness: 1.5295340589458237, h_index: 45, i10_index: 205 } Copy updated_date: "2022-01-02T00:00:00" Copy works_api_url: "https://api.openalex.org/works?filter=author.id:A5023888391", Copy works_count: 38 Copy x_concepts: [\ {\ id: "https://openalex.org/C41008148",\ wikidata: null,\ display_name: "Computer science",\ level: 0,\ score: 97.4\ },\ {\ id: "https://openalex.org/C17744445",\ wikidata: null,\ display_name: "Political science",\ level: 0,\ score: 78.9\ }\ ] --- # Get lists of entities | OpenAlex technical documentation It's easy to get a list of entity objects from from the API:`/`. Here's an example: * Get a list of _all_ the topics in OpenAlex: [`https://api.openalex.org/topics`](https://api.openalex.org/topics) This query returns a `meta` object with details about the query, a `results` list of [`Topic`](https://docs.openalex.org/api-entities/topics/topic-object) objects, and an empty [`group_by`](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) list: Copy meta: { count: 4516, db_response_time_ms: 81, page: 1, per_page: 25 }, results: [\ // long list of Topic entities\ ], group_by: [] // empty Listing entities is a lot more useful when you add parameters to [page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) , [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , [search](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) , and [sort](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) them. Keep reading to learn how to do that. [PreviousSelect fields](https://docs.openalex.org/how-to-use-the-api/get-single-entities/select-fields) [NextPaging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) Last updated 22 days ago --- # Tutorials | OpenAlex technical documentation We're working on making a collection of tutorials to demonstrate how to use OpenAlex to answer all sorts of questions. Check back often for more! Here's what we have currently * [Turn the page](https://github.com/ourresearch/openalex-api-tutorials/blob/main/notebooks/getting-started/paging.ipynb) - Use [paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) to collect all of the works from an author. * [Monitoring Open Access publications for a given institution](https://github.com/ourresearch/openalex-api-tutorials/blob/main/notebooks/institutions/oa-percentage.ipynb) - Learn how to filter and group with the API. * [What are the publication sources located in Japan](https://github.com/ourresearch/openalex-api-tutorials/blob/main/notebooks/institutions/japan_sources.ipynb) ? - Use the `source` entity to look at a country's publications over time. * [Calculate the h-index for a given author](https://github.com/ourresearch/openalex-api-tutorials/blob/main/notebooks/authors/hirsch-index.ipynb) - Use filtering, sorting, and paging to get citation counts and calculate the h-index, an author-level metric. * [How are my institution's researchers collaborating with people around the globe?](https://github.com/ourresearch/openalex-api-tutorials/blob/main/notebooks/institutions/uw-collaborators.ipynb) - Learn about `institutions` in OpenAlex while exploring the international research collaborations made by a university. * [Getting started with OpenAlex Premium](https://github.com/ourresearch/openalex-api-tutorials/blob/main/notebooks/getting-started/premium.ipynb) - Use your Premium API Key to download the latest updates from our API and keep your data in sync with ours. * [Introduction to openalexR](https://trangdata.github.io/openalexR-webinar/) - In this R notebook, an accompaniment to the [webinar](https://openalex.org/webinars) on openalexR, you'll learn the basics of using the openalexR library to get data from OpenAlex. [PreviousPostgres schema diagram](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database/postgres-schema-diagram) [NextReport bugs](https://docs.openalex.org/additional-help/report-bugs) Last updated 22 days ago --- # Random result | OpenAlex technical documentation You can get a random result by using the string `random` where an ID would normally go. OMG that's so random! Each time you call this URL you'll get a different entity. Examples: * Get a random institution: [`https://api.openalex.org/institutions/random`](https://api.openalex.org/institutions/random) * Get a random concept: [`https://api.openalex.org/concepts/random`](https://api.openalex.org/concepts/random) [PreviousGet single entities](https://docs.openalex.org/how-to-use-the-api/get-single-entities) [NextSelect fields](https://docs.openalex.org/how-to-use-the-api/get-single-entities/select-fields) Last updated 21 days ago --- # Search concepts | OpenAlex technical documentation These are the original OpenAlex Concepts, which are being deprecated in favor of [Topics](https://docs.openalex.org/api-entities/topics) . We will continue to provide these Concepts for Works, but we will not be actively maintaining, updating, or providing support for these concepts. Unless you have a good reason to be relying on them, we encourage you to look into [Topics](https://docs.openalex.org/api-entities/topics) instead. The best way to search for concepts is to use the `search` query parameter, which searches the [`display_name`](https://docs.openalex.org/api-entities/concepts/concept-object#display_name) and [`description`](https://docs.openalex.org/api-entities/concepts/concept-object#description) fields. Example: * Search concepts' `display_name` and `description` for "artificial intelligence": [https://api.openalex.org/concepts?search=artificial intelligence](https://api.openalex.org/concepts?search=artificial%20intelligence) You can read more about search [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. [](https://docs.openalex.org/api-entities/concepts/search-concepts#search-a-specific-field) Search a specific field ------------------------------------------------------------------------------------------------------------------------ You can also use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , allowing you to fine-tune the fields you're searching over. To do this, you append `.search` to the end of the property you are filtering for: * Get concepts with "medical" in the `display_name`: [https://api.openalex.org/concepts?filter=display\_name.search:medical](https://api.openalex.org/concepts?filter=display_name.search:medical) The following field can be searched as a filter within concepts: Search filter Field that is searched [`display_name.search`](https://docs.openalex.org/api-entities/concepts/filter-concepts#display_name.search) [`display_name`](https://docs.openalex.org/api-entities/concepts/concept-object#display_name) You can also use the filter `default.search`, which works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/concepts/search-concepts#search-concepts) . [](https://docs.openalex.org/api-entities/concepts/search-concepts#autocomplete-concepts) Autocomplete concepts -------------------------------------------------------------------------------------------------------------------- You can autocomplete concepts to create a very fast type-ahead style search function: * Autocomplete concepts with "comp" in the `display_name`: [https://api.openalex.org/autocomplete/concepts?q=comp](https://api.openalex.org/autocomplete/concepts?q=comp) This returns a list of concepts with the description set as the hint: Copy { "results": [\ {\ "id": "https://openalex.org/C41008148",\ "display_name": "Computer science",\ "hint": "theoretical study of the formal foundation enabling the automated processing or computation of information, for example on a computer or over a data transmission network",\ "cited_by_count": 392939277,\ "works_count": 76722605,\ "entity_type": "concept",\ "external_id": "https://www.wikidata.org/wiki/Q21198"\ },\ ...\ ] } Read more in the [autocomplete page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) in the API guide. [PreviousFilter concepts](https://docs.openalex.org/api-entities/concepts/filter-concepts) [NextGroup concepts](https://docs.openalex.org/api-entities/concepts/group-concepts) Last updated 22 days ago * [Search a specific field](https://docs.openalex.org/api-entities/concepts/search-concepts#search-a-specific-field) * [Autocomplete concepts](https://docs.openalex.org/api-entities/concepts/search-concepts#autocomplete-concepts) --- # API Overview | OpenAlex technical documentation The API is the primary way to get OpenAlex data. It's free and requires no authentication. The daily limit for API calls is 100,000 requests per user per day. For best performance, [add your email](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool) to all API requests, like `[[email protected]](https://docs.openalex.org/cdn-cgi/l/email-protection) `. [](https://docs.openalex.org/how-to-use-the-api/api-overview#learn-more-about-the-api) Learn more about the API -------------------------------------------------------------------------------------------------------------------- * [Get single entities](https://docs.openalex.org/how-to-use-the-api/get-single-entities) * [Get lists of entities](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities) — Learn how to use [paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) , [filtering](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , and [sorting](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) * [Get groups of entities](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) — Group and count entities in different ways * [Rate limits and authentication](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication) — Learn about joining the [polite pool](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool) * [Tutorials](https://docs.openalex.org/additional-help/tutorials) — Hands-on examples with code [](https://docs.openalex.org/how-to-use-the-api/api-overview#client-libraries) Client Libraries ---------------------------------------------------------------------------------------------------- There are several third-party libraries you can use to get data from OpenAlex: * [openalexR](https://github.com/ropensci/openalexR) (R) * [OpenAlex2Pajek](https://github.com/bavla/OpenAlex/tree/main/OpenAlex2Pajek) (R) * [KtAlex](https://github.com/benedekh/KtAlex) (Kotlin) * [PyAlex](https://github.com/J535D165/pyalex) (Python) * [diophila](https://pypi.org/project/diophila/) (Python) * [OpenAlexAPI](https://pypi.org/project/openalexapi/) (Python) If you're looking for a visual interface, you can also check out the free [VOSviewer](https://www.vosviewer.com/) , which lets you make network visualizations based on OpenAlex data: [PreviousAboutness endpoint (/text)](https://docs.openalex.org/api-entities/aboutness-endpoint-text) [Nextxpac](https://docs.openalex.org/how-to-use-the-api/xpac) Last updated 22 days ago * [Learn more about the API](https://docs.openalex.org/how-to-use-the-api/api-overview#learn-more-about-the-api) * [Client Libraries](https://docs.openalex.org/how-to-use-the-api/api-overview#client-libraries) --- # Get lists of institutions | OpenAlex technical documentation You can get lists of institutions: * Get _all_ institutions in OpenAlex [https://api.openalex.org/institutions](https://api.openalex.org/institutions) Which returns a response like this: Copy { "meta": { "count": 108618, "db_response_time_ms": 32, "page": 1, "per_page": 25 }, "results": [\ {\ "id": "https://openalex.org/I27837315",\ "ror": "https://ror.org/00jmfr291",\ "display_name": "University of Michigan–Ann Arbor",\ // more fields (removed to save space)\ },\ {\ "id": "https://openalex.org/I201448701",\ "ror": "https://ror.org/00cvxb145",\ "display_name": "University of Washington",\ // more fields (removed to save space)\ },\ // more results (removed to save space)\ ], "group_by": [] } [](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions#page-and-sort-institutions) Page and sort institutions -------------------------------------------------------------------------------------------------------------------------------------------- By default we return 25 results per page. You can change this default and [page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) through institutions with the `per-page` and `page` parameters: * Get the second page of institutions results, with 50 results returned per page [https://api.openalex.org/institutions?per-page=50&page=2](https://api.openalex.org/institutions?per-page=50&page=2) You also can [sort results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) with the `sort` parameter: * Sort institutions by cited by count, descending [https://api.openalex.org/institutions?sort=cited\_by\_count:desc](https://api.openalex.org/institutions?sort=cited_by_count:desc) Continue on to learn how you can [filter](https://docs.openalex.org/api-entities/institutions/filter-institutions) and [search](https://docs.openalex.org/api-entities/institutions/search-institutions) lists of institutions. [](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions#sample-institutions) Sample institutions ------------------------------------------------------------------------------------------------------------------------------ You can use `sample` to get a random batch of institutions. Read more about sampling and how to add a `seed` value [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) . * Get 50 random institutions [https://api.openalex.org/institutions?sample=50&per-page=50](https://api.openalex.org/institutions?sample=50&per-page=50) [](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions#select-fields) Select fields ------------------------------------------------------------------------------------------------------------------ You can use `select` to limit the fields that are returned in a list of institutions. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id`, `ror`, and `display_name` within institutions results [https://api.openalex.org/institutions?select=id,display\_name,ror](https://api.openalex.org/institutions?select=id,display_name,ror) [PreviousGet a single institution](https://docs.openalex.org/api-entities/institutions/get-a-single-institution) [NextFilter institutions](https://docs.openalex.org/api-entities/institutions/filter-institutions) Last updated 22 days ago * [Page and sort institutions](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions#page-and-sort-institutions) * [Sample institutions](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions#sample-institutions) * [Select fields](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions#select-fields) --- # Group concepts | OpenAlex technical documentation These are the original OpenAlex Concepts, which are being deprecated in favor of [Topics](https://docs.openalex.org/api-entities/topics) . We will continue to provide these Concepts for Works, but we will not be actively maintaining, updating, or providing support for these concepts. Unless you have a good reason to be relying on them, we encourage you to look into [Topics](https://docs.openalex.org/api-entities/topics) instead. You can group concepts with the `group_by` parameter: * Get counts of concepts by [`level`](https://docs.openalex.org/api-entities/concepts/concept-object#level) : [https://api.openalex.org/concepts?group\_by=level](https://api.openalex.org/concepts?group_by=level) Or you can group using one the attributes below. It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. ### [](https://docs.openalex.org/api-entities/concepts/group-concepts#concepts-group_by-__-attributes) `/concepts` group\_by \_\_ attributes * [`ancestors.id`](https://docs.openalex.org/api-entities/concepts/concept-object#ancestors) * [`cited_by_count`](https://docs.openalex.org/api-entities/concepts/concept-object#cited_by_count) * [`has_wikidata`](https://docs.openalex.org/api-entities/concepts/filter-concepts#has_wikidata) * [`level`](https://docs.openalex.org/api-entities/concepts/concept-object#level) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/concepts/concept-object#summary_stats) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/concepts/concept-object#summary_stats) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/concepts/concept-object#summary_stats) * [`works_count`](https://docs.openalex.org/api-entities/concepts/concept-object#works_count) [PreviousSearch concepts](https://docs.openalex.org/api-entities/concepts/search-concepts) [NextAboutness endpoint (/text)](https://docs.openalex.org/api-entities/aboutness-endpoint-text) Last updated 22 days ago --- # Get lists of funders | OpenAlex technical documentation You can get lists of funders: * Get _all_ funders in OpenAlex [https://api.openalex.org/funders](https://api.openalex.org/funders) Which returns a response like this: Copy { "meta": { "count": 32437, "db_response_time_ms": 26, "page": 1, "per_page": 25 }, "results": [\ {\ "id": "https://openalex.org/F4320321001",\ "display_name": "National Natural Science Foundation of China",\ // more fields (removed to save space)\ },\ {\ "id": "https://openalex.org/F4320306076",\ "display_name": "National Science Foundation",\ // more fields (removed to save space)\ },\ // more results (removed to save space)\ ], "group_by": [] } [](https://docs.openalex.org/api-entities/funders/get-lists-of-funders#page-and-sort-funders) Page and sort funders ------------------------------------------------------------------------------------------------------------------------ By default we return 25 results per page. You can change this default and [page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) through funders with the `per-page` and `page` parameters: * Get the second page of funders results, with 50 results returned per page [https://api.openalex.org/funders?per-page=50&page=2](https://api.openalex.org/funders?per-page=50&page=2) You also can [sort results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) with the `sort` parameter: * Sort funders by display name, descending [https://api.openalex.org/funders?sort=display\_name:desc](https://api.openalex.org/funders?sort=display_name:desc) Continue on to learn how you can [filter](https://docs.openalex.org/api-entities/funders/filter-funders) and [search](https://docs.openalex.org/api-entities/funders/search-funders) lists of funders. [](https://docs.openalex.org/api-entities/funders/get-lists-of-funders#sample-funders) Sample funders ---------------------------------------------------------------------------------------------------------- You can use `sample` to get a random batch of funders. Read more about sampling and how to add a `seed` value [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) . * Get 10 random funders [https://api.openalex.org/funders?sample=10](https://api.openalex.org/funders?sample=10) [](https://docs.openalex.org/api-entities/funders/get-lists-of-funders#select-fields) Select fields -------------------------------------------------------------------------------------------------------- You can use `select` to limit the fields that are returned in a list of funders. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id`, `display_name`, and `alternate_titles` within funders results [https://api.openalex.org/funders?select=id,display\_name,alternate\_titles](https://api.openalex.org/funders?select=id,display_name,alternate_titles) [PreviousGet a single funder](https://docs.openalex.org/api-entities/funders/get-a-single-funder) [NextFilter funders](https://docs.openalex.org/api-entities/funders/filter-funders) Last updated 22 days ago * [Page and sort funders](https://docs.openalex.org/api-entities/funders/get-lists-of-funders#page-and-sort-funders) * [Sample funders](https://docs.openalex.org/api-entities/funders/get-lists-of-funders#sample-funders) * [Select fields](https://docs.openalex.org/api-entities/funders/get-lists-of-funders#select-fields) --- # Group awards | OpenAlex technical documentation You can group awards with the `group_by` parameter: * Get counts of awards by funder: [`https://api.openalex.org/awards?group_by=funder.id`](https://api.openalex.org/awards?group_by=funder.id) Or you can group using one of the attributes below. It's best to [read about group by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) before trying these out. It will show you how results are formatted, the ## default limit of 200 results per call, and how to sort results. [](https://docs.openalex.org/api-entities/awards/group-awards#awards-group_by-attributes) `/awards` group\_by attributes ----------------------------------------------------------------------------------------------------------------------------- * [`currency`](https://docs.openalex.org/api-entities/awards/award-object#currency) * [`end_year`](https://docs.openalex.org/api-entities/awards/award-object#end_year) * [`funder.id`](https://docs.openalex.org/api-entities/awards/award-object#funder) * [`funder_scheme`](https://docs.openalex.org/api-entities/awards/award-object#funder_scheme) * [`funding_type`](https://docs.openalex.org/api-entities/awards/award-object#funding_type) * [`lead_investigator.affiliation.country`](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) * [`provenance`](https://docs.openalex.org/api-entities/awards/award-object#provenance) * [`start_year`](https://docs.openalex.org/api-entities/awards/award-object#start_year) [PreviousSearch awards](https://docs.openalex.org/api-entities/awards/search-awards) [NextGeo](https://docs.openalex.org/api-entities/geo) Last updated 22 days ago --- # Search awards | OpenAlex technical documentation The best way to search for awards is to use the `search` query parameter, which searches across the [`display_name`](https://docs.openalex.org/api-entities/awards/award-object#display_name) and [`description`](https://docs.openalex.org/api-entities/awards/award-object#description) fields. * Get awards that mention "machine learning": [`https://api.openalex.org/awards?search=machine%20learning`](https://api.openalex.org/awards?search=machine%20learning) You can read more about search [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . It will show you how relevance score is calculated and how words are stemmed to improve search results. [](https://docs.openalex.org/api-entities/awards/search-awards#search-a-specific-field) Search a specific field -------------------------------------------------------------------------------------------------------------------- You can also use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , allowing you to fine-tune the fields you're searching over. To do this, append `.search` to the end of the property you're filtering for: * Get awards where the display name includes "climate": [`https://api.openalex.org/awards?filter=display_name.search:climate`](https://api.openalex.org/awards?filter=display_name.search:climate) The following fields can be searched as a filter within awards: Search filter Field that is searched [`display_name.search`](https://docs.openalex.org/api-entities/awards/filter-awards#display_name.search) [`display_name`](https://docs.openalex.org/api-entities/awards/award-object#display_name) [`description.search`](https://docs.openalex.org/api-entities/awards/filter-awards#description.search) [`description`](https://docs.openalex.org/api-entities/awards/award-object#description) You can also use the filter `default.search`, which works the same as using the `search` parameter. [PreviousFilter awards](https://docs.openalex.org/api-entities/awards/filter-awards) [NextGroup awards](https://docs.openalex.org/api-entities/awards/group-awards) Last updated 21 days ago --- # xpac | OpenAlex technical documentation On November 4, 2025, we added over 190 million new works to OpenAlex as part of [a rewrite codenamed Walden](https://blog.openalex.org/openalex-rewrite-walden-launch/) . This expansion pack (XPAC for short) includes all of DataCite, plus thousands of institutional and subject-area repositories. For more information on XPAC, see the [Walden release notes](https://docs.google.com/document/d/1SPZ7QFcPddCHYt1pZP1UCIuqbfBY22lSHwgPA8RQyUY/edit?tab=t.0) . [](https://docs.openalex.org/how-to-use-the-api/xpac#why-are-xpac-works-excluded-by-default) Why are XPAC works excluded by default? ----------------------------------------------------------------------------------------------------------------------------------------- The data quality on XPAC works is generally not as high as on other works, but it will improve over time. To avoid surprising users with a sudden change in result counts and quality, XPAC works are **excluded by default** from API results. [](https://docs.openalex.org/how-to-use-the-api/xpac#the-include_xpac-parameter) The `include_xpac` parameter ------------------------------------------------------------------------------------------------------------------ You can include XPAC works in your results by adding the `include_xpac=true` parameter to any works endpoint call: * Get all works, including those in XPAC: [`https://api.openalex.org/works?include_xpac=true`](https://api.openalex.org/works?include_xpac=true) Without this parameter, you'll get approximately 278 million works. With `include_xpac=true`, you'll get over 470 million works. The `include_xpac` parameter defaults to `false`. You must explicitly set it to `true` to include XPAC works in your results. [](https://docs.openalex.org/how-to-use-the-api/xpac#the-is_xpac-field) The `is_xpac` field ------------------------------------------------------------------------------------------------ Each work has an [`is_xpac`](https://docs.openalex.org/api-entities/works/work-object#is_xpac) boolean field that indicates whether it's part of the XPAC dataset. You can also use this as a filter: * Get only XPAC works: [`https://api.openalex.org/works?include_xpac=true&filter=is_xpac:true`](https://api.openalex.org/works?include_xpac=true&filter=is_xpac:true) [PreviousAPI Overview](https://docs.openalex.org/how-to-use-the-api/api-overview) [NextGet single entities](https://docs.openalex.org/how-to-use-the-api/get-single-entities) Last updated 22 days ago * [Why are XPAC works excluded by default?](https://docs.openalex.org/how-to-use-the-api/xpac#why-are-xpac-works-excluded-by-default) * [The include\_xpac parameter](https://docs.openalex.org/how-to-use-the-api/xpac#the-include_xpac-parameter) * [The is\_xpac field](https://docs.openalex.org/how-to-use-the-api/xpac#the-is_xpac-field) --- # Upload to your database | OpenAlex technical documentation Now that you have a copy of the OpenAlex data you can do one these: * upload it to a [data warehouse](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse) * upload it to a [relational database](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database) [PreviousDownload to your machine](https://docs.openalex.org/download-all-data/download-to-your-machine) [NextLoad to a data warehouse](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse) Last updated 22 days ago --- # Report bugs | OpenAlex technical documentation Oh no, you found a bug! 🕷️ Please tell us about it using [this form](https://openalex.org/help) on our help page. [PreviousTutorials](https://docs.openalex.org/additional-help/tutorials) [NextFAQ](https://docs.openalex.org/additional-help/faq) Last updated 22 days ago --- # Sort entity lists | OpenAlex technical documentation Use the `?sort` parameter to specify the property you want your list sorted by. You can sort by these properties, where they exist: * `display_name` * `cited_by_count` * `works_count` * `publication_date` * `relevance_score` (only exists if there's a [search filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists#search) active) By default, sort direction is ascending. You can reverse this by appending `:desc` to the sort key like `works_count:desc`. You can sort by multiple properties by providing multiple sort keys, separated by commas. Examples: * All works, sorted by `cited_by_count` (highest counts first) [`https://api.openalex.org/works?sort=cited_by_count:desc`](https://api.openalex.org/works?sort=cited_by_count:desc) * All sources, in alphabetical order by title: [`https://api.openalex.org/sources?sort=display_name`](https://api.openalex.org/sources?sort=display_name) You can sort by relevance\_score when searching: * Sort by year, then by relevance\_score when searching for "bioplastics": [`https://api.openalex.org/works?filter=display_name.search:bioplastics&sort=publication_year:desc,relevance_score:desc`](https://api.openalex.org/works?filter=display_name.search:bioplastics&sort=publication_year:desc,relevance_score:desc) An error is thrown if attempting to sort by `relevance_score` without a search query. [PreviousSearch entities](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) [NextSelect fields](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) Last updated 22 days ago --- # Funder object | OpenAlex technical documentation These are the fields in a funder object. When you use the API to get a single funder or lists of funders, this is what's returned. ### [](https://docs.openalex.org/api-entities/funders/funder-object#alternate_titles) `alternate_titles` _List:_ A list of alternate titles for this funder. Copy alternate_titles: [\ "US National Institutes of Health",\ "Institutos Nacionales de la Salud",\ "NIH"\ ] ### [](https://docs.openalex.org/api-entities/funders/funder-object#cited_by_count) `cited_by_count` _Integer:_ The total number [`Works`](https://docs.openalex.org/api-entities/works/work-object) that cite a work linked to this funder. Copy cited_by_count: 7823467 ### [](https://docs.openalex.org/api-entities/funders/funder-object#country_code) `country_code` _String:_ The country where this funder is located, represented as an [ISO two-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) . Copy country_code: "US" ### [](https://docs.openalex.org/api-entities/funders/funder-object#counts_by_year) `counts_by_year` _List:_ The values of [`works_count`](https://docs.openalex.org/api-entities/funders/funder-object#works_count) and [`cited_by_count`](https://docs.openalex.org/api-entities/funders/funder-object#cited_by_count) for _each_ of the last ten years, binned by year. To put it another way: for every listed year, you can see how many new works are linked to this funder, and how many times _any_ work linked to this funder was cited. Years with zero citations and zero works have been removed so you will need to add those back in if you need them. ### [](https://docs.openalex.org/api-entities/funders/funder-object#created_date) `created_date` _String:_ The date this `Funder` object was created in the OpenAlex dataset, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. ### [](https://docs.openalex.org/api-entities/funders/funder-object#description) `description` _String:_ A short description of this funder, taken from [Wikidata](https://docs.openalex.org/api-entities/funders/funder-object#ids) . ### [](https://docs.openalex.org/api-entities/funders/funder-object#display_name) `display_name` _String:_ The primary name of the funder. ### [](https://docs.openalex.org/api-entities/funders/funder-object#grants_count) `grants_count` _Integer:_ The number of grants linked to this funder. ### [](https://docs.openalex.org/api-entities/funders/funder-object#homepage_url) `homepage_url` _String:_ The URL for this funder's primary homepage. ### [](https://docs.openalex.org/api-entities/funders/funder-object#id) `id` _String:_ The OpenAlex ID for this funder. ### [](https://docs.openalex.org/api-entities/funders/funder-object#ids) `ids` _Object:_ All the external identifiers that we know about for this funder. IDs are expressed as URIs whenever possible. Possible ID types: * `crossref` _String:_ this funder's Crossref ID * `doi` _String:_ this funder's DOI * `openalex` _String:_ this funder's [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) * `ror` _String:_ this funder's ROR ID * `wikidata` _String:_ this funder's [Wikidata ID](https://www.wikidata.org/wiki/Wikidata:Identifiers) ### [](https://docs.openalex.org/api-entities/funders/funder-object#image_thumbnail_url) `image_thumbnail_url` _String:_ Same as [`image_url`](https://docs.openalex.org/api-entities/funders/funder-object#image_url) , but it's a smaller image. This is usually a hotlink to a wikimedia image. You can change the `width=300` parameter in the URL if you want a different thumbnail size. ### [](https://docs.openalex.org/api-entities/funders/funder-object#image_url) `image_url` _String:_ URL where you can get an image representing this funder. Usually this a hotlink to a Wikimedia image, and usually it's a seal or logo. ### [](https://docs.openalex.org/api-entities/funders/funder-object#roles) `roles` _List:_ List of role objects, which include the `role` (one of `institution`, `funder`, or `publisher`), the `id` ([OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) ), and the `works_count`. In many cases, a single organization does not fit neatly into one role. For example, Yale University is a single organization that is a research university, funds research studies, and publishes an academic journal. The `roles` property links the OpenAlex entities together for a single organization, and includes counts for the works associated with each role. The `roles` list of an entity ([Funder](https://docs.openalex.org/api-entities/funders) , [Publisher](https://docs.openalex.org/api-entities/publishers) , or [Institution](https://docs.openalex.org/api-entities/institutions) ) always includes itself. In the case where an organization only has one role, the `roles` will be a list of length one, with itself as the only item. ### [](https://docs.openalex.org/api-entities/funders/funder-object#summary_stats) `summary_stats` _Object:_ Citation metrics for this funder * `2yr_mean_citedness` _Float_: The 2-year mean citedness for this source. Also known as [impact factor](https://en.wikipedia.org/wiki/Impact_factor) . We use the year prior to the current year for the citations (the numerator) and the two years prior to that for the citation-receiving publications (the denominator). * `h_index` _Integer_: The [_h_\-index](https://en.wikipedia.org/wiki/H-index) for this funder. * `i10_index` _Integer_: The [i-10 index](https://en.wikipedia.org/wiki/Author-level_metrics#i-10-index) for this funder. While the _h_\-index and the i-10 index are normally author-level metrics and the 2-year mean citedness is normally a journal-level metric, they can be calculated for any set of papers, so we include them for funders. ### [](https://docs.openalex.org/api-entities/funders/funder-object#updated_date) `updated_date` _String:_ The last time anything in this funder object changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. This date is updated for _any change at all_, including increases in various counts. ### [](https://docs.openalex.org/api-entities/funders/funder-object#works_count) `works_count` _Integer:_ The number of works linked to this funder. [PreviousFunders](https://docs.openalex.org/api-entities/funders) [NextGet a single funder](https://docs.openalex.org/api-entities/funders/get-a-single-funder) Last updated 22 days ago * [alternate\_titles](https://docs.openalex.org/api-entities/funders/funder-object#alternate_titles) * [cited\_by\_count](https://docs.openalex.org/api-entities/funders/funder-object#cited_by_count) * [country\_code](https://docs.openalex.org/api-entities/funders/funder-object#country_code) * [counts\_by\_year](https://docs.openalex.org/api-entities/funders/funder-object#counts_by_year) * [created\_date](https://docs.openalex.org/api-entities/funders/funder-object#created_date) * [description](https://docs.openalex.org/api-entities/funders/funder-object#description) * [display\_name](https://docs.openalex.org/api-entities/funders/funder-object#display_name) * [grants\_count](https://docs.openalex.org/api-entities/funders/funder-object#grants_count) * [homepage\_url](https://docs.openalex.org/api-entities/funders/funder-object#homepage_url) * [id](https://docs.openalex.org/api-entities/funders/funder-object#id) * [ids](https://docs.openalex.org/api-entities/funders/funder-object#ids) * [image\_thumbnail\_url](https://docs.openalex.org/api-entities/funders/funder-object#image_thumbnail_url) * [image\_url](https://docs.openalex.org/api-entities/funders/funder-object#image_url) * [roles](https://docs.openalex.org/api-entities/funders/funder-object#roles) * [summary\_stats](https://docs.openalex.org/api-entities/funders/funder-object#summary_stats) * [updated\_date](https://docs.openalex.org/api-entities/funders/funder-object#updated_date) * [works\_count](https://docs.openalex.org/api-entities/funders/funder-object#works_count) Copy counts_by_year: [\ {\ year: 2021,\ works_count: 4211,\ cited_by_count: 120939\ },\ {\ year: 2020,\ works_count: 4363,\ cited_by_count: 119531\ },\ \ // and so forth\ ] Copy created_date: "2023-02-13" Copy description: "medical research organization in the United States" Copy display_name: "National Institutes of Health" Copy grants_count: 7109 Copy homepage_url: "http://www.nih.gov/" Copy id: "https://openalex.org/F4320332161" Copy ids: { openalex: "https://openalex.org/F4320332161", ror: "https://ror.org/01cwqze88", wikidata: "https://www.wikidata.org/entity/Q390551", crossref: "100000002", doi: "https://doi.org/10.13039/100000002" } Copy image_thumbnail_url: "https://commons.wikimedia.org/w/index.php?title=Special:Redirect/file/NIH 2013 logo vertical.svg&width=300" Copy image_url: "https://commons.wikimedia.org/w/index.php?title=Special:Redirect/file/NIH 2013 logo vertical.svg" Copy roles: [\ {\ role: "funder",\ id: "https://openalex.org/F4320308380",\ works_count: 1004,\ },\ {\ role: "publisher",\ id: "https://openalex.org/P4310315589",\ works_count: 13986,\ },\ {\ role: "institution",\ id: "https://openalex.org/I32971472",\ works_count: 250031,\ }\ ] Copy summary_stats: { 2yr_mean_citedness: 5.065784263815827, h_index: 985, i10_index: 176682 } Copy updated_date: "2023-04-21T16:54:19.012138" Copy works_count: 260210 --- # Rate limits and authentication | OpenAlex technical documentation The API is rate-limited. The limits are: * max 100,000 calls every day, and also * max 10 requests every second. If you hit the API more than 100k times in a day or more than 10 in a second, you'll get `429` errors instead of useful data. Are those rate limits too low for you? No problem! We can raise those limits as high as you need if you subscribe to [our Premium plan](https://openalex.org/pricing) . And if you're an academic researcher we can likely do it for free; just drop us a line at [\[email protected\]](https://docs.openalex.org/cdn-cgi/l/email-protection#780b0d0808170a0c3817081d1619141d0056170a1f) . Are you scrolling through a list of entities, calling the API for each? You can go way faster by squishing 50 requests into one using our [OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . Here's [a tutorial](https://blog.ourresearch.org/fetch-multiple-dois-in-one-openalex-api-request/) showing how. [](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool) The polite pool -------------------------------------------------------------------------------------------------------------------- The OpenAlex API doesn't require authentication. However, it is helpful for us to know who's behind each API call, for two reasons: * It allows us to get in touch with the user if something's gone wrong--for instance, their script has run amok and we've needed to start blocking or throttling their usage. * It lets us report back to our funders, which helps us keep the lights on. Like Crossref (whose approach we are shamelessly stealing), we separate API users into two pools, the polite pool and the common pool. The polite pool has more consistent response times. It's where you want to be. To get into the polite pool, you just have to give us an email where we can contact you. You can give us this email in one of two ways: * Add the `[[email protected]](https://docs.openalex.org/cdn-cgi/l/email-protection) ` parameter in your API request, like this: [`https://api.openalex.org/[email protected]`](https://api.openalex.org/works?mailto=you@example.com) * Add `mailto:[[email protected]](https://docs.openalex.org/cdn-cgi/l/email-protection) ` somewhere in your User-Agent request header. [](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#authentication) Authentication ------------------------------------------------------------------------------------------------------------------ You don't need an API key to use OpenAlex. However, [premium users](https://help.openalex.org/hc/en-us/articles/24397762024087-Pricing) do get an API key, which grants higher API limits and enables the use of special filters like [`from_updated_date`](https://docs.openalex.org/api-entities/works/filter-works#from_updated_date) . Using the API key is simple; just add it to your URL using the api\_key param. * Get a list of all works, using the api key 424242: [`https://api.openalex.org/works?api_key=424242`](https://api.openalex.org/works?api_key=424242) [](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#usage-tips) Usage tips ---------------------------------------------------------------------------------------------------------- ### [](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#calling-the-api-in-your-browser) Calling the API in your browser Because the API is all GET requests without fancy authentication, you can view any request in your browser. This is a very useful and pleasant way to explore the API and debug scripts; we use it all the time. However, this is _much_ nicer if you install an extension to pretty-print the JSON; [JSONVue (Chrome)](https://chrome.google.com/webstore/detail/jsonvue/chklaanhfefbnpoihckbnefhakgolnmc) and [JSONView (Firefox)](https://addons.mozilla.org/en-US/firefox/addon/jsonview) are popular, free choices. Here's what an API response looks like with one of these extensions enabled: ![](https://docs.openalex.org/~gitbook/image?url=https%3A%2F%2Fi.imgur.com%2FE7mNLph.png&width=768&dpr=4&quality=100&sign=fd9e5660&sv=2) A lot prettier than cURL [PreviousGet groups of entities](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) [NextOpenAlex snapshot](https://docs.openalex.org/download-all-data/openalex-snapshot) Last updated 22 days ago * [The polite pool](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool) * [Authentication](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#authentication) * [Usage tips](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#usage-tips) * [Calling the API in your browser](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#calling-the-api-in-your-browser) --- # Search funders | OpenAlex technical documentation The best way to search for funders is to use the `search` query parameter, which searches the [`display_name`](https://docs.openalex.org/api-entities/funders/funder-object#display_name) , the [`alternate_titles`](https://docs.openalex.org/api-entities/funders/funder-object#alternate_titles) , and the [`description`](https://github.com/ourresearch/openalex-elastic-api/blob/master/docs/api-entities/funders/funder_object.md#description) fields. Example: * Search funders' `display_name`, `alternate_titles`, and `description` for "health": [`https://api.openalex.org/funders?search=health`](https://api.openalex.org/funders?search=health) You can read more about search [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. [](https://docs.openalex.org/api-entities/funders/search-funders#search-a-specific-field) Search a specific field ---------------------------------------------------------------------------------------------------------------------- You can also use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , allowing you to fine-tune the fields you're searching over. To do this, you append `.search` to the end of the property you are filtering for: * Get funders with "florida" in the `display_name`: [`https://api.openalex.org/funders?filter=display_name.search:florida`](https://api.openalex.org/funders?filter=display_name.search:florida) The following fields can be searched as a filter within funders: Search filter Field that is searched [`display_name.search`](https://docs.openalex.org/api-entities/funders/filter-funders#display_name.search) [`display_name`](https://docs.openalex.org/api-entities/funders/funder-object#display_name) [`description.search`](https://docs.openalex.org/api-entities/funders/filter-funders#description.search) [`description`](https://docs.openalex.org/api-entities/funders/funder-object#description) You can also use the filter `default.search`, which works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/funders/search-funders#search-funders) . [](https://docs.openalex.org/api-entities/funders/search-funders#autocomplete-funders) Autocomplete funders ---------------------------------------------------------------------------------------------------------------- You can autocomplete funders to create a very fast type-ahead style search function: * Autocomplete funders with "national sci" in the [`display_name`](https://docs.openalex.org/api-entities/funders/funder-object#display_name) : [https://api.openalex.org/autocomplete/funders?q=national+sci](https://api.openalex.org/autocomplete/funders?q=national+sci) This returns a list of funders with the funder location set as the hint: Copy "results": [\ {\ "id": "https://openalex.org/F4320306076",\ "display_name": "National Science Foundation",\ "hint": null,\ "cited_by_count": 6705777,\ "works_count": 264303,\ "entity_type": "funder",\ "external_id": "https://ror.org/021nxhr62"\ },\ ...\ ] Read more in the [autocomplete page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) in the API guide. [PreviousFilter funders](https://docs.openalex.org/api-entities/funders/filter-funders) [NextGroup funders](https://docs.openalex.org/api-entities/funders/group-funders) Last updated 21 days ago * [Search a specific field](https://docs.openalex.org/api-entities/funders/search-funders#search-a-specific-field) * [Autocomplete funders](https://docs.openalex.org/api-entities/funders/search-funders#autocomplete-funders) --- # Concepts | OpenAlex technical documentation These are the original OpenAlex Concepts, which are being deprecated in favor of [Topics](https://docs.openalex.org/api-entities/topics) . We will continue to provide these Concepts for Works, but we will not be actively maintaining, updating, or providing support for these concepts. Unless you have a good reason to be relying on them, we encourage you to look into [Topics](https://docs.openalex.org/api-entities/topics) instead. Concepts are abstract ideas that works are about. OpenAlex indexes about 65k concepts. * Get all the concepts used by OpenAlex: [`https://api.openalex.org/concepts`](https://api.openalex.org/concepts) The [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for OpenAlex concepts is the Wikidata ID, and each of our concepts has one, because all OpenAlex concepts are also Wikidata concepts. Concepts are hierarchical, like a tree. There are 19 root-level concepts, and six layers of descendants branching out from them, containing about 65 thousand concepts all told. This concept tree is a modified version of [the one created by MAG](https://arxiv.org/abs/1805.12216) . You can view all the concepts and their position in the tree [as a spreadsheet here](https://docs.google.com/spreadsheets/d/1LBFHjPt4rj_9r0t0TTAlT68NwOtNH8Z21lBMsJDMoZg/edit#gid=1473310811) . About 85% of works are tagged with at least one concept (here's the [breakdown of concept counts per work](https://docs.google.com/spreadsheets/d/17DoJjyl1XVNZdVWs7fUy91z69U2tD8qtnBsaqJ-Zigo/edit#gid=0) ). [](https://docs.openalex.org/api-entities/concepts#how-concepts-are-assigned) How concepts are assigned ------------------------------------------------------------------------------------------------------------ Each work is tagged with multiple concepts, based on the title, abstract, and the title of its host venue. The tagging is done using an automated classifier that was trained on MAG’s corpus; you can read more about the development and operation of this classifier in [Automated concept tagging for OpenAlex, an open index of scholarly articles.](https://docs.google.com/document/d/1OgXSLriHO3Ekz0OYoaoP_h0sPcuvV4EqX7VgLLblKe4/edit) You can implement the classifier yourself using [our models and code](https://github.com/ourresearch/openalex-concept-tagging) . A score is available for each [concept in a work](https://docs.openalex.org/api-entities/works/work-object#concepts) , showing the classifier's confidence in choosing that concept. However, when assigning a lower-level child concept, we also assign all of its parent concepts all the way up to the root. This means that some concept assignment scores will be 0.0. The tagger adds concepts to works written in different languages, but it is optimized for English. Concepts are linked to works via the [`concepts`](https://docs.openalex.org/api-entities/works/work-object#concepts) property, and to other concepts via the [`ancestors`](https://docs.openalex.org/api-entities/concepts/concept-object#ancestors) and [`related_concepts`](https://docs.openalex.org/api-entities/concepts/concept-object#related_concepts) properties. [](https://docs.openalex.org/api-entities/concepts#whats-next) What's next ------------------------------------------------------------------------------- Learn more about what you can do with concepts: * [The Concept object](https://docs.openalex.org/api-entities/concepts/concept-object) * [Get a single concept](https://docs.openalex.org/api-entities/concepts/get-a-single-concept) * [Get lists of concepts](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts) * [Filter concepts](https://docs.openalex.org/api-entities/concepts/filter-concepts) * [Search concepts](https://docs.openalex.org/api-entities/concepts/search-concepts) * [Group concepts](https://docs.openalex.org/api-entities/concepts/group-concepts) [PreviousRegions](https://docs.openalex.org/api-entities/geo/regions) [NextConcept object](https://docs.openalex.org/api-entities/concepts/concept-object) Last updated 22 days ago * [How concepts are assigned](https://docs.openalex.org/api-entities/concepts#how-concepts-are-assigned) * [What's next](https://docs.openalex.org/api-entities/concepts#whats-next) --- # Download to your machine | OpenAlex technical documentation First off: anyone can get the data for free. While the files are hosted on [S3](https://aws.amazon.com/s3/) and we’ll be using Amazon tools in these instructions, you don’t need an Amazon account. Many thanks to the [AWS Open Data program](https://aws.amazon.com/opendata/) . They cover the data-transfer fees (about $70 per download!) so users don't have to. Before you load the snapshot contents to your database, you’ll need to get the files that make it up onto your own computer. There are exceptions, like [loading to redshift from s3](https://docs.aws.amazon.com/redshift/latest/dg/tutorial-loading-data.html) or using an ETL product like [Xplenty](https://xplenty.com/) with an S3 connector. If either of these apply to you, see if the [snapshot data format](https://docs.openalex.org/download-all-data/snapshot-data-format) is enough to get you started. The easiest way to get the files is with the Amazon Web Services Command Line Interface (AWS CLI). Sample commands in this documentation will use the AWS CLI. You can find instructions for installing it on your system here: [https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) You can also browse the snapshot files using the AWS console here: [https://openalex.s3.amazonaws.com/browse.html](https://openalex.s3.amazonaws.com/browse.html) . This browser and the CLI will work without an account. This shell command will copy everything in the `openalex` S3 bucket to a local folder named `openalex-snapshot`. It'll take up roughly 300GB of disk space. Copy aws s3 sync "s3://openalex" "openalex-snapshot" --no-sign-request If you download the snapshot into an existing folder, you'll need to use the [`aws s3 sync`](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) `--delete` flag to remove files from any previous downloads. You can also remove the contents of destination folder manually. If you don't, you will see duplicate Entities that have moved from one file to another between snapshot updates. The size of the snapshot will change over time. You can check the current size before downloading by looking at the output of: Copy aws s3 ls --summarize --human-readable --no-sign-request --recursive "s3://openalex/" You should get a file structure like this (edited for length - there are more objects in the actual bucket): Copy openalex-snapshot/ ├── LICENSE.txt ├── RELEASE_NOTES.txt └── data ├── authors │ ├── manifest │ └── updated_date=2021-12-28 │ ├── 0000_part_00.gz │ └── 0001_part_00.gz ├── concepts │ ├── manifest │ └── updated_date=2021-12-28 │ ├── 0000_part_00.gz │ └── 0001_part_00.gz ├── institutions │ ├── manifest │ └── updated_date=2021-12-28 │ ├── 0000_part_00.gz │ └── 0001_part_00.gz ├── sources │ ├── manifest │ └── updated_date=2021-12-28 │ ├── 0000_part_00.gz │ └── 0001_part_00.gz └── works ├── manifest └── updated_date=2021-12-28 ├── 0000_part_00.gz └── 0001_part_00.gz [PreviousSnapshot data format](https://docs.openalex.org/download-all-data/snapshot-data-format) [NextUpload to your database](https://docs.openalex.org/download-all-data/upload-to-your-database) Last updated 22 days ago --- # Filter awards | OpenAlex technical documentation You can filter awards with the `filter` parameter: * Get awards from the National Science Foundation: [`https://api.openalex.org/awards?filter=funder.id:F4320306076`](https://api.openalex.org/awards?filter=funder.id:F4320306076) It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query. [](https://docs.openalex.org/api-entities/awards/filter-awards#awards-attribute-filters) `/awards` attribute filters ------------------------------------------------------------------------------------------------------------------------- You can filter using these attributes of the [`Award`](https://docs.openalex.org/api-entities/awards/award-object) object: * [`amount`](https://docs.openalex.org/api-entities/awards/award-object#amount) * [`currency`](https://docs.openalex.org/api-entities/awards/award-object#currency) * [`doi`](https://docs.openalex.org/api-entities/awards/award-object#doi) * [`end_year`](https://docs.openalex.org/api-entities/awards/award-object#end_year) * [`funder.doi`](https://docs.openalex.org/api-entities/awards/award-object#funder) * [`funder.id`](https://docs.openalex.org/api-entities/awards/award-object#funder) * [`funder.ror`](https://docs.openalex.org/api-entities/awards/award-object#funder) * [`funder_award_id`](https://docs.openalex.org/api-entities/awards/award-object#funder_award_id) * [`funder_name`](https://docs.openalex.org/api-entities/awards/award-object#funder) * [`funder_scheme`](https://docs.openalex.org/api-entities/awards/award-object#funder_scheme) * [`funded_outputs`](https://docs.openalex.org/api-entities/awards/award-object#funded_outputs) * [`funded_outputs_count`](https://docs.openalex.org/api-entities/awards/award-object#funded_outputs_count) * [`funding_type`](https://docs.openalex.org/api-entities/awards/award-object#funding_type) * [`id`](https://docs.openalex.org/api-entities/awards/award-object#id) * [`lead_investigator.affiliation.country`](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) * [`lead_investigator.affiliation.name`](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) * [`lead_investigator.family_name`](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) * [`lead_investigator.given_name`](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) * [`lead_investigator.orcid`](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) * [`provenance`](https://docs.openalex.org/api-entities/awards/award-object#provenance) * [`start_year`](https://docs.openalex.org/api-entities/awards/award-object#start_year) [](https://docs.openalex.org/api-entities/awards/filter-awards#awards-convenience-filters) `/awards` convenience filters ----------------------------------------------------------------------------------------------------------------------------- These filters aren't attributes of the [`Award`](https://docs.openalex.org/api-entities/awards/award-object) object, but they're included to address some common use cases: ### [](https://docs.openalex.org/api-entities/awards/filter-awards#default.search) `default.search` Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/awards/search-awards) for awards. ### [](https://docs.openalex.org/api-entities/awards/filter-awards#display_name.search) `display_name.search` Value: a search string Returns awards with a [`display_name`](https://docs.openalex.org/api-entities/awards/award-object#display_name) containing the given string. * Get awards with "climate" in the name: [`https://api.openalex.org/awards?filter=display_name.search:climate`](https://api.openalex.org/awards?filter=display_name.search:climate) ### [](https://docs.openalex.org/api-entities/awards/filter-awards#description.search) `description.search` Value: a search string Returns awards with a [`description`](https://docs.openalex.org/api-entities/awards/award-object#description) containing the given string. [PreviousGet lists of awards](https://docs.openalex.org/api-entities/awards/get-lists-of-awards) [NextSearch awards](https://docs.openalex.org/api-entities/awards/search-awards) Last updated 21 days ago * [/awards attribute filters](https://docs.openalex.org/api-entities/awards/filter-awards#awards-attribute-filters) * [/awards convenience filters](https://docs.openalex.org/api-entities/awards/filter-awards#awards-convenience-filters) * [default.search](https://docs.openalex.org/api-entities/awards/filter-awards#default.search) * [display\_name.search](https://docs.openalex.org/api-entities/awards/filter-awards#display_name.search) * [description.search](https://docs.openalex.org/api-entities/awards/filter-awards#description.search) --- # Postgres schema diagram | OpenAlex technical documentation This is a diagram of one possible schema for storing the OpenAlex data in a [relational database](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database) . It's the one used in our examples here, but may not be the best one for the ways you'll use the dataset. (click to embiggen) [PreviousLoad to a relational database](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database) [NextTutorials](https://docs.openalex.org/additional-help/tutorials) Last updated 22 days ago --- # Source object | OpenAlex technical documentation These are the fields in a source object. When you use the API to get a single source or lists of sources, this is what's returned. ### [](https://docs.openalex.org/api-entities/sources/source-object#abbreviated_title) abbreviated\_title _String:_ An abbreviated title obtained from the [ISSN Centre](https://issn.org/) . Copy abbreviated_title: "J. addict. med. ther. sci." ### [](https://docs.openalex.org/api-entities/sources/source-object#alternate_titles) alternate\_titles _Array:_ Alternate titles for this source, as obtained from the [ISSN Centre](https://issn.org/) and individual work records, like Crossref DOIs, that carry the source name as a string. These are commonly abbreviations or translations of the source's canonical name. Copy alternate_titles: [\ "ACRJ"\ ] ### [](https://docs.openalex.org/api-entities/sources/source-object#apc_prices) apc\_prices _List:_ List of objects, each with `price` (_Integer_) and `currency` (_String_). Article processing charge information, taken directly from [DOAJ](https://doaj.org/) . Copy apc_prices: [\ {\ price: 3920,\ currency: "GBP"\ }\ ] ### [](https://docs.openalex.org/api-entities/sources/source-object#apc_usd) apc\_usd _Integer:_ The source's article processing charge in US Dollars, if available from [DOAJ](https://doaj.org/) . The `apc_usd` value is calculated by taking the APC price (see [`apc_prices`](https://docs.openalex.org/api-entities/sources/source-object#apc_prices) ) with a currency of USD if it is available. If it's not available, we convert the first available value from `apc_prices` into USD, using recent exchange rates. ### [](https://docs.openalex.org/api-entities/sources/source-object#cited_by_count) `cited_by_count` _Integer:_ The total number of [`Works`](https://docs.openalex.org/api-entities/works/work-object) that cite a `Work` hosted in this source. ### [](https://docs.openalex.org/api-entities/sources/source-object#country_code) `country_code` _String:_ The country that this source is associated with, represented as an [ISO two-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) . ### [](https://docs.openalex.org/api-entities/sources/source-object#counts_by_year) `counts_by_year` _List:_ [`works_count`](https://docs.openalex.org/api-entities/sources/source-object#works_count) and [`cited_by_count`](https://docs.openalex.org/api-entities/sources/source-object#cited_by_count) for each of the last ten years, binned by year. To put it another way: each year, you can see how many new works this source started hosting, and how many times _any_ work in this source got cited. If the source was founded less than ten years ago, there will naturally be fewer than ten years in this list. Years with zero citations and zero works have been removed so you will need to add those in if you need them. ### [](https://docs.openalex.org/api-entities/sources/source-object#created_date) `created_date` _String:_ The date this `Source` object was created in the OpenAlex dataset, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. ### [](https://docs.openalex.org/api-entities/sources/source-object#display_name) `display_name` _String:_ The name of the source. ### [](https://docs.openalex.org/api-entities/sources/source-object#homepage_url) `homepage_url` _String:_ The starting page for navigating the contents of this source; the homepage for this source's website. ### [](https://docs.openalex.org/api-entities/sources/source-object#host_organization) `host_organization` _String:_ The host organization for this source as an [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) . This will be an [`Institution.id`](https://docs.openalex.org/api-entities/institutions/institution-object#id) if the source is a repository, and a [`Publisher.id`](https://docs.openalex.org/api-entities/publishers/publisher-object#id) if the source is a journal, conference, or eBook platform (based on the [`type`](https://docs.openalex.org/api-entities/sources/source-object#type) field). ### [](https://docs.openalex.org/api-entities/sources/source-object#host_organization_lineage) `host_organization_lineage` _List:_ [OpenAlex IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) — See [`Publisher.lineage`](https://docs.openalex.org/api-entities/publishers/publisher-object#lineage) . This will only be included if the [`host_organization`](https://docs.openalex.org/api-entities/sources/source-object#host_organization) is a publisher (and not if the `host_organization` is an institution). ### [](https://docs.openalex.org/api-entities/sources/source-object#host_organization_name) `host_organization_name` _String:_ The `display_name` from the [host\_organization](https://docs.openalex.org/api-entities/sources/source-object#host_organization) , shown for convenience. ### [](https://docs.openalex.org/api-entities/sources/source-object#id) `id` _String:_ The [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for this source. ### [](https://docs.openalex.org/api-entities/sources/source-object#ids) `ids` _Object:_ All the external identifiers that we know about for this source. IDs are expressed as URIs whenever possible. Possible ID types: * `fatcat` (_String_: this source's [Fatcat](https://fatcat.wiki/) ID) * `issn` (_List:_ a list of this source's ISSNs. Same as [`Source.issn`](https://docs.openalex.org/api-entities/sources/source-object#issn) ) * `issn_l` (_String:_ this source's ISSN-L. Same as [`Source.issn_l`](https://docs.openalex.org/api-entities/sources/source-object#issn_l) ) * `mag` (_Integer:_ this source's [Microsoft Academic Graph](https://www.microsoft.com/en-us/research/project/microsoft-academic-graph/) ID) * `openalex` (_String:_ this source's [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) . Same as [`Source.id`](https://docs.openalex.org/api-entities/sources/source-object#id) ) * `wikidata` (_String_: this source's [Wikidata](https://www.wikidata.org/wiki/Wikidata:Main_Page) ID) Many sources are missing one or more ID types (either because we don't know the ID, or because it was never assigned). Keys for null IDs are not displayed. Example[](https://docs.openalex.org/api-entities/sources/source-object#example) ### [](https://docs.openalex.org/api-entities/sources/source-object#is_core) `is_core` _Boolean:_ Whether this source is identified as a "core source" by [CWTS](https://www.cwts.nl/) , used in the [Open Leiden Ranking](https://open.leidenranking.com/) of universities around the world. The list of core sources can be found [here](https://zenodo.org/records/10949671) . ### [](https://docs.openalex.org/api-entities/sources/source-object#is_in_doaj) `is_in_doaj` _Boolean:_ Whether this is a journal listed in the [Directory of Open Access Journals](https://doaj.org/) (DOAJ). ### [](https://docs.openalex.org/api-entities/sources/source-object#is_oa) `is_oa` _Boolean:_ Whether this is currently fully-open-access source. This could be `true` for a preprint repository where everything uploaded is free to read, or for a [Gold](https://en.wikipedia.org/wiki/Open_access#Colour_naming_system) or [Diamond](https://en.wikipedia.org/wiki/Diamond_open_access) open access journal, where all newly published Works are available for free under an open license. We say "currently" because the status of a source can change over time. It's common for journals to "flip" to Gold OA, after which they may make only future articles open or also open their back catalogs. It's entirely possible for a source to say `is_oa: true`, but for an article from last year to require a subscription. ### [](https://docs.openalex.org/api-entities/sources/source-object#issn) `issn` _List:_ The [ISSNs](https://en.wikipedia.org/wiki/International_Standard_Serial_Number) used by this source. Many publications have multiple ISSNs , so [ISSN-L](https://docs.openalex.org/api-entities/sources/source-object#issn_l) should be used when possible. ### [](https://docs.openalex.org/api-entities/sources/source-object#issn_l) `issn_l` _String:_ The [ISSN-L](https://en.wikipedia.org/wiki/International_Standard_Serial_Number#Linking_ISSN) identifying this source. This is the [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for sources. ISSN is a global and unique ID for serial publications. However, different media versions of a given publication (e.g., print and electronic) often have _different_ ISSNs. This is why we can't have nice things. The ISSN-L or Linking ISSN solves the problem by designating a single canonical ISSN for all media versions of the title. It's _usually_ the same as the print ISSN. ### [](https://docs.openalex.org/api-entities/sources/source-object#societies) societies _Array:_ Societies on whose behalf the source is published and maintained, obtained from our [crowdsourced list](https://blog.ourresearch.org/society-list/) . Thanks! ### [](https://docs.openalex.org/api-entities/sources/source-object#summary_stats) `summary_stats` _Object:_ Citation metrics for this source * `2yr_mean_citedness` _Float_: The 2-year mean citedness for this source. Also known as [impact factor](https://en.wikipedia.org/wiki/Impact_factor) . We use the year prior to the current year for the citations (the numerator) and the two years prior to that for the citation-receiving publications (the denominator). * `h_index` _Integer_: The [_h_\-index](https://en.wikipedia.org/wiki/H-index) for this source. * `i10_index` _Integer_: The [i-10 index](https://en.wikipedia.org/wiki/Author-level_metrics#i-10-index) for this source. While the _h_\-index and the i-10 index are normally author-level metrics, they can be calculated for any set of papers, so we include them for sources. ### [](https://docs.openalex.org/api-entities/sources/source-object#type) `type` _String:_ The type of source, which will be one of: `journal`, `repository`, `conference`, `ebook platform`, `book series`, `metadata`, or `other`. ### [](https://docs.openalex.org/api-entities/sources/source-object#updated_date) `updated_date` _String:_ The last time anything in this `Source` object changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. This date is updated for _any change at all_, including increases in various counts. ### [](https://docs.openalex.org/api-entities/sources/source-object#works_api_url) `works_api_url` _String:_ A URL that will get you a list of all this source's `Works`. We express this as an API URL (instead of just listing the works themselves) because sometimes a source's publication list is too long to reasonably fit into a single `Source` object. ### [](https://docs.openalex.org/api-entities/sources/source-object#works_count) `works_count` _Integer:_ The number of [`Works`](https://docs.openalex.org/api-entities/works/work-object) this source hosts. ### [](https://docs.openalex.org/api-entities/sources/source-object#x_concepts) `x_concepts` `x_concepts` will be deprecated and removed soon. We will be replacing this functionality with [`Topics`](https://docs.openalex.org/api-entities/topics) instead. _List:_ The `Concepts` most frequently applied to works hosted by this source. Each is represented as a [dehydrated Concept](https://docs.openalex.org/api-entities/concepts/concept-object#the-dehydratedconcept-object) object, with one additional attribute: `score` (_Float_): The strength of association between this source and the listed concept, from 0-100. [](https://docs.openalex.org/api-entities/sources/source-object#the-dehydratedsource-object) The `DehydratedSource` object ------------------------------------------------------------------------------------------------------------------------------- The `DehydratedSource` is stripped-down `Source` object, with most of its properties removed to save weight. Its only remaining properties are: * [`display_name`](https://docs.openalex.org/api-entities/sources/source-object#display_name) * [`host_organization`](https://docs.openalex.org/api-entities/sources/source-object#host_organization) * [`host_organization_lineage`](https://docs.openalex.org/api-entities/sources/source-object#host_organization_lineage) * [`host_organization_name`](https://docs.openalex.org/api-entities/sources/source-object#host_organization_name) * [`id`](https://docs.openalex.org/api-entities/sources/source-object#id) * [`is_core`](https://docs.openalex.org/api-entities/sources/source-object#is_core) * [`is_in_doaj`](https://docs.openalex.org/api-entities/sources/source-object#is_in_doaj) * [`is_oa`](https://docs.openalex.org/api-entities/sources/source-object#is_oa) * [`issn`](https://docs.openalex.org/api-entities/sources/source-object#issn) * [`issn_l`](https://docs.openalex.org/api-entities/sources/source-object#issn_l) * [`type`](https://docs.openalex.org/api-entities/sources/source-object#type) [PreviousSources](https://docs.openalex.org/api-entities/sources) [NextGet a single source](https://docs.openalex.org/api-entities/sources/get-a-single-source) Last updated 22 days ago * [abbreviated\_title](https://docs.openalex.org/api-entities/sources/source-object#abbreviated_title) * [alternate\_titles](https://docs.openalex.org/api-entities/sources/source-object#alternate_titles) * [apc\_prices](https://docs.openalex.org/api-entities/sources/source-object#apc_prices) * [apc\_usd](https://docs.openalex.org/api-entities/sources/source-object#apc_usd) * [cited\_by\_count](https://docs.openalex.org/api-entities/sources/source-object#cited_by_count) * [country\_code](https://docs.openalex.org/api-entities/sources/source-object#country_code) * [counts\_by\_year](https://docs.openalex.org/api-entities/sources/source-object#counts_by_year) * [created\_date](https://docs.openalex.org/api-entities/sources/source-object#created_date) * [display\_name](https://docs.openalex.org/api-entities/sources/source-object#display_name) * [homepage\_url](https://docs.openalex.org/api-entities/sources/source-object#homepage_url) * [host\_organization](https://docs.openalex.org/api-entities/sources/source-object#host_organization) * [host\_organization\_lineage](https://docs.openalex.org/api-entities/sources/source-object#host_organization_lineage) * [host\_organization\_name](https://docs.openalex.org/api-entities/sources/source-object#host_organization_name) * [id](https://docs.openalex.org/api-entities/sources/source-object#id) * [ids](https://docs.openalex.org/api-entities/sources/source-object#ids) * [is\_core](https://docs.openalex.org/api-entities/sources/source-object#is_core) * [is\_in\_doaj](https://docs.openalex.org/api-entities/sources/source-object#is_in_doaj) * [is\_oa](https://docs.openalex.org/api-entities/sources/source-object#is_oa) * [issn](https://docs.openalex.org/api-entities/sources/source-object#issn) * [issn\_l](https://docs.openalex.org/api-entities/sources/source-object#issn_l) * [societies](https://docs.openalex.org/api-entities/sources/source-object#societies) * [summary\_stats](https://docs.openalex.org/api-entities/sources/source-object#summary_stats) * [type](https://docs.openalex.org/api-entities/sources/source-object#type) * [updated\_date](https://docs.openalex.org/api-entities/sources/source-object#updated_date) * [works\_api\_url](https://docs.openalex.org/api-entities/sources/source-object#works_api_url) * [works\_count](https://docs.openalex.org/api-entities/sources/source-object#works_count) * [x\_concepts](https://docs.openalex.org/api-entities/sources/source-object#x_concepts) * [The DehydratedSource object](https://docs.openalex.org/api-entities/sources/source-object#the-dehydratedsource-object) Copy apc_usd: 5200 Copy cited_by_count: 133702 Copy country_code: "GB" Copy counts_by_year: [\ {\ year: 2021,\ works_count: 4338,\ cited_by_count: 127268\ },\ {\ year: 2020,\ works_count: 4363,\ cited_by_count: 119531\ },\ \ // and so forth\ ] Copy created_date: "2017-08-08" Copy display_name: "PeerJ" Copy homepage_url: "http://www.peerj.com/" Copy id: "https://openalex.org/P4310320595" Copy host_organization_lineage: [\ "https://openalex.org/P4310321285",\ "https://openalex.org/P4310319900",\ "https://openalex.org/P4310319965"\ ] Copy host_organization_name: "Elsevier BV" Copy id: "https://openalex.org/S1983995261" Copy ids: { openalex: "https://openalex.org/S1983995261", issn_l: "2167-8359", issn: [\ "2167-8359"\ ], mag: 1983995261, fatcat: "https://fatcat.wiki/container/z3ijzhu7zzey3f7jwws7rzopoq", wikidata: "https://www.wikidata.org/entity/Q96326029" } Copy is_core: true Copy is_in_doaj: true Copy is_oa: true Copy issn: ["2167-8359"] Copy issn_l: "2167-8359" Copy societies: [\ {\ "url": "http://www.counseling.org/",\ "organization": "American Counseling Association on behalf of the American College Counseling Association"\ }\ ] Copy summary_stats: { 2yr_mean_citedness: 1.5295340589458237, h_index: 105, i10_index: 5045 } Copy type: "journal" Copy updated_date: "2022-01-02T00:00:00" Copy works_api_url: "https://api.openalex.org/works?filter=primary_location.source.id:S1983995261", Copy works_count: 20184 Copy x_concepts: [\ {\ id: "https://openalex.org/C86803240",\ wikidata: null,\ display_name: "Biology",\ level: 0,\ score: 86.7\ },\ {\ id: "https://openalex.org/C185592680",\ wikidata: null,\ display_name: "Chemistry",\ level: 0,\ score: 51.4\ },\ \ // and so forth\ ] --- # Award object | OpenAlex technical documentation These are the fields in an award object. When you use the API to get a single award or lists of awards, this is what's returned. ### [](https://docs.openalex.org/api-entities/awards/award-object#id) `id` _String:_ The OpenAlex ID for this award. Copy id: "https://openalex.org/G5453342221" ### [](https://docs.openalex.org/api-entities/awards/award-object#display_name) `display_name` _String:_ The name or title of the award, if available. Copy display_name: "Implementation of activities described in the Roadmap to Fusion during Horizon 2020 through a Joint programme of the members of the EUROfusion consortium" ### [](https://docs.openalex.org/api-entities/awards/award-object#description) `description` _String:_ A description of the award, if available. Copy description: "A Roadmap to the realization of fusion energy was adopted by the EFDA system at the end of 2012. The roadmap aims at achieving all the necessary know-how to start the construction of a demonstration power plant (DEMO) by 2030..." ### [](https://docs.openalex.org/api-entities/awards/award-object#funder_award_id) `funder_award_id` _String:_ The award identifier as assigned by the funder (e.g., the grant number). Copy funder_award_id: "633053" ### [](https://docs.openalex.org/api-entities/awards/award-object#funder) `funder` _Object:_ Information about the funder that issued this award. Contains: * `id`: _String_ — The OpenAlex ID for the funder * `display_name`: _String_ — The name of the funder * `ror`: _String_ — The ROR ID for the funder * `doi`: _String_ — The DOI for the funder ### [](https://docs.openalex.org/api-entities/awards/award-object#funded_outputs) `funded_outputs` _List:_ A list of OpenAlex Work IDs that were funded by this award. ### [](https://docs.openalex.org/api-entities/awards/award-object#funded_outputs_count) `funded_outputs_count` _Integer:_ The number of works funded by this award. ### [](https://docs.openalex.org/api-entities/awards/award-object#amount) `amount` _Float:_ The monetary amount of the award, if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#currency) `currency` _String:_ The currency of the award amount (e.g., "USD", "EUR"), if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#funding_type) `funding_type` _String:_ The type of funding provided (e.g., "grant", "fellowship"), if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#funder_scheme) `funder_scheme` _String:_ The specific funding scheme or program under which the award was made, if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#start_date) `start_date` _String:_ The start date of the award, formatted as an ISO 8601 date string, if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#end_date) `end_date` _String:_ The end date of the award, formatted as an ISO 8601 date string, if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#start_year) `start_year` _Integer:_ The year when the award started, if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#end_year) `end_year` _Integer:_ The year when the award ends or ended, if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#landing_page_url) `landing_page_url` _String:_ A URL for the award's landing page, if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#doi) `doi` _String:_ The DOI for this award, if available. ### [](https://docs.openalex.org/api-entities/awards/award-object#provenance) `provenance` _String:_ The source of this award data. ### [](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) `lead_investigator` _Object:_ Information about the lead investigator (principal investigator) for this award, if available. Contains: * `given_name`: _String_ — The given name of the investigator * `family_name`: _String_ — The family name of the investigator * `orcid`: _String_ — The ORCID identifier of the investigator * `role_start`: _String_ — When the investigator started this role * `affiliation`: _Object_ — The investigator's institutional affiliation ### [](https://docs.openalex.org/api-entities/awards/award-object#co_lead_investigator) `co_lead_investigator` _Object:_ Information about the co-lead investigator, if available. Has the same structure as [`lead_investigator`](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) . ### [](https://docs.openalex.org/api-entities/awards/award-object#investigators) `investigators` _List:_ A list of all investigators associated with this award. Each investigator has the same structure as [`lead_investigator`](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) . ### [](https://docs.openalex.org/api-entities/awards/award-object#works_api_url) `works_api_url` _String:_ A URL that returns a list of works funded by this award. ### [](https://docs.openalex.org/api-entities/awards/award-object#created_date) `created_date` _String:_ The date this Award object was created in the OpenAlex dataset, expressed as an ISO 8601 date string. ### [](https://docs.openalex.org/api-entities/awards/award-object#updated_date) `updated_date` _String:_ The last time anything in this award object changed, expressed as an ISO 8601 date string. [PreviousAwards](https://docs.openalex.org/api-entities/awards) [NextGet a single award](https://docs.openalex.org/api-entities/awards/get-a-single-award) Last updated 22 days ago * [id](https://docs.openalex.org/api-entities/awards/award-object#id) * [display\_name](https://docs.openalex.org/api-entities/awards/award-object#display_name) * [description](https://docs.openalex.org/api-entities/awards/award-object#description) * [funder\_award\_id](https://docs.openalex.org/api-entities/awards/award-object#funder_award_id) * [funder](https://docs.openalex.org/api-entities/awards/award-object#funder) * [funded\_outputs](https://docs.openalex.org/api-entities/awards/award-object#funded_outputs) * [funded\_outputs\_count](https://docs.openalex.org/api-entities/awards/award-object#funded_outputs_count) * [amount](https://docs.openalex.org/api-entities/awards/award-object#amount) * [currency](https://docs.openalex.org/api-entities/awards/award-object#currency) * [funding\_type](https://docs.openalex.org/api-entities/awards/award-object#funding_type) * [funder\_scheme](https://docs.openalex.org/api-entities/awards/award-object#funder_scheme) * [start\_date](https://docs.openalex.org/api-entities/awards/award-object#start_date) * [end\_date](https://docs.openalex.org/api-entities/awards/award-object#end_date) * [start\_year](https://docs.openalex.org/api-entities/awards/award-object#start_year) * [end\_year](https://docs.openalex.org/api-entities/awards/award-object#end_year) * [landing\_page\_url](https://docs.openalex.org/api-entities/awards/award-object#landing_page_url) * [doi](https://docs.openalex.org/api-entities/awards/award-object#doi) * [provenance](https://docs.openalex.org/api-entities/awards/award-object#provenance) * [lead\_investigator](https://docs.openalex.org/api-entities/awards/award-object#lead_investigator) * [co\_lead\_investigator](https://docs.openalex.org/api-entities/awards/award-object#co_lead_investigator) * [investigators](https://docs.openalex.org/api-entities/awards/award-object#investigators) * [works\_api\_url](https://docs.openalex.org/api-entities/awards/award-object#works_api_url) * [created\_date](https://docs.openalex.org/api-entities/awards/award-object#created_date) * [updated\_date](https://docs.openalex.org/api-entities/awards/award-object#updated_date) Copy funder: { id: "https://openalex.org/F4320337670", display_name: "H2020 Euratom", doi: "https://doi.org/10.13039/100010687" } Copy funded_outputs: [\ "https://openalex.org/W2959949293",\ "https://openalex.org/W3181133739",\ "https://openalex.org/W2755925992",\ // ... and more\ ] Copy funded_outputs_count: 1350 Copy amount: 678800000.0 Copy currency: "EUR" Copy funding_type: "grant" Copy funder_scheme: "EURATOM" Copy start_date: "2014-01-01" Copy end_date: "2022-12-31" Copy start_year: 2014 Copy end_year: 2022 Copy landing_page_url: "https://cordis.europa.eu/project/id/633053" Copy doi: "https://doi.org/10.3030/633053" Copy provenance: "crossref_work" Copy lead_investigator: { given_name: "Jane", family_name: "Smith", orcid: "https://orcid.org/0000-0001-2345-6789", role_start: "2020-01-01", affiliation: { name: "University of Example", country: "US", ids: [\ {\ id: "https://ror.org/example",\ type: "ror",\ asserted_by: "publisher"\ }\ ] } } Copy works_api_url: "https://api.openalex.org/works?filter=awards.id:G5453342221" Copy created_date: "2022-12-12T12:41:08" Copy updated_date: "2022-12-14T06:02:06" --- # Publisher object | OpenAlex technical documentation Here are the fields in a publisher object. When you use the API to get a single publisher or lists of publishers, this is what's returned. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#alternate_titles) `alternate_titles` _List:_ A list of alternate titles for this publisher. Copy alternate_titles: [\ "Elsevier",\ "elsevier.com",\ "Elsevier Science",\ "Uitg. Elsevier",\ "السفیر", \ "السویر", \ "انتشارات الزویر", \ "لودویک السفیر", \ "爱思唯尔"\ ] ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#cited_by_count) `cited_by_count` _Integer:_ The number of citations to works that are linked to this publisher through journals or other sources. For example, if a publisher publishes 27 journals and those 27 journals have 3,050 works, this number is the sum of the cited\_by\_count values for all of those 3,050 works. Copy cited_by_count: 407508754 ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#country_codes) `country_codes` _List:_ The countries where the publisher is primarily located, as an [ISO two-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) . ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#counts_by_year) `counts_by_year` _List:_ The values of [`works_count`](https://docs.openalex.org/api-entities/publishers/publisher-object#works_count) and [`cited_by_count`](https://docs.openalex.org/api-entities/publishers/publisher-object#cited_by_count) for _each_ of the last ten years, binned by year. To put it another way: for every listed year, you can see how many new works are linked to this publisher, and how many times _any_ work linked to this publisher was cited. Years with zero citations and zero works have been removed so you will need to add those back in if you need them. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#created_date) `created_date` _String:_ The date this `Publisher` object was created in the OpenAlex dataset, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#display_name) `display_name` _String:_ The primary name of the publisher. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#hierarchy_level) `hierarchy_level` _Integer:_ The hierarchy level for this publisher. A publisher with hierarchy level 0 has no parent publishers. A hierarchy level 1 publisher has one parent above it, and so on. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#id) `id` _String:_ The OpenAlex ID for this publisher. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#ids) `ids` _Object:_ All the external identifiers that we know about for this publisher. IDs are expressed as URIs whenever possible. Possible ID types: * `openalex` _String:_ this publishers's [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) * `ror` _String:_ this publisher's ROR ID * `wikidata` _String:_ this publisher's [Wikidata ID](https://www.wikidata.org/wiki/Wikidata:Identifiers) ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#image_thumbnail_url) `image_thumbnail_url` _String:_ Same as [`image_url`](https://docs.openalex.org/api-entities/publishers/publisher-object#image_url-1) , but it's a smaller image. This is usually a hotlink to a wikimedia image. You can change the `width=300` parameter in the URL if you want a different thumbnail size. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#image_url) `image_url` _String:_ URL where you can get an image representing this publisher. Usually this a hotlink to a Wikimedia image, and usually it's a seal or logo. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#lineage) `lineage` _List:_ [OpenAlex IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) of publishers. The list will include this publisher's ID, as well as any parent publishers. If this publisher's `hierarchy_level` is 0, this list will only contain its own ID. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#parent_publisher) `parent_publisher` _String:_ An OpenAlex ID linking to the direct parent of the publisher. This will be null if the publisher's `hierarchy_level` is 0. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#roles) `roles` _List:_ List of role objects, which include the `role` (one of `institution`, `funder`, or `publisher`), the `id` ([OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) ), and the `works_count`. In many cases, a single organization does not fit neatly into one role. For example, Yale University is a single organization that is a research university, funds research studies, and publishes an academic journal. The `roles` property links the OpenAlex entities together for a single organization, and includes counts for the works associated with each role. The `roles` list of an entity ([Funder](https://docs.openalex.org/api-entities/funders) , [Publisher](https://docs.openalex.org/api-entities/publishers) , or [Institution](https://docs.openalex.org/api-entities/institutions) ) always includes itself. In the case where an organization only has one role, the `roles` will be a list of length one, with itself as the only item. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#sources_api_url) `sources_api_url` _String:_ An URL that will get you a list of all the sources published by this publisher. We express this as an API URL (instead of just listing the sources themselves) because there might be thousands of sources linked to a publisher, and that's too many to fit here. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#summary_stats) `summary_stats` _Object:_ Citation metrics for this publisher * `2yr_mean_citedness` _Float_: The 2-year mean citedness for this source. Also known as [impact factor](https://en.wikipedia.org/wiki/Impact_factor) . We use the year prior to the current year for the citations (the numerator) and the two years prior to that for the citation-receiving publications (the denominator). * `h_index` _Integer_: The [_h_\-index](https://en.wikipedia.org/wiki/H-index) for this publisher. * `i10_index` _Integer_: The [i-10 index](https://en.wikipedia.org/wiki/Author-level_metrics#i-10-index) for this publisher. While the _h_\-index and the i-10 index are normally author-level metrics and the 2-year mean citedness is normally a journal-level metric, they can be calculated for any set of papers, so we include them for publishers. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#updated_date) `updated_date` _String:_ The last time anything in this publisher object changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. This date is updated for _any change at all_, including increases in various counts. ### [](https://docs.openalex.org/api-entities/publishers/publisher-object#works_count) `works_count` _Integer:_ The number of works published by this publisher. [PreviousPublishers](https://docs.openalex.org/api-entities/publishers) [NextGet a single publisher](https://docs.openalex.org/api-entities/publishers/get-a-single-publisher) Last updated 22 days ago * [alternate\_titles](https://docs.openalex.org/api-entities/publishers/publisher-object#alternate_titles) * [cited\_by\_count](https://docs.openalex.org/api-entities/publishers/publisher-object#cited_by_count) * [country\_codes](https://docs.openalex.org/api-entities/publishers/publisher-object#country_codes) * [counts\_by\_year](https://docs.openalex.org/api-entities/publishers/publisher-object#counts_by_year) * [created\_date](https://docs.openalex.org/api-entities/publishers/publisher-object#created_date) * [display\_name](https://docs.openalex.org/api-entities/publishers/publisher-object#display_name) * [hierarchy\_level](https://docs.openalex.org/api-entities/publishers/publisher-object#hierarchy_level) * [id](https://docs.openalex.org/api-entities/publishers/publisher-object#id) * [ids](https://docs.openalex.org/api-entities/publishers/publisher-object#ids) * [image\_thumbnail\_url](https://docs.openalex.org/api-entities/publishers/publisher-object#image_thumbnail_url) * [image\_url](https://docs.openalex.org/api-entities/publishers/publisher-object#image_url) * [lineage](https://docs.openalex.org/api-entities/publishers/publisher-object#lineage) * [parent\_publisher](https://docs.openalex.org/api-entities/publishers/publisher-object#parent_publisher) * [roles](https://docs.openalex.org/api-entities/publishers/publisher-object#roles) * [sources\_api\_url](https://docs.openalex.org/api-entities/publishers/publisher-object#sources_api_url) * [summary\_stats](https://docs.openalex.org/api-entities/publishers/publisher-object#summary_stats) * [updated\_date](https://docs.openalex.org/api-entities/publishers/publisher-object#updated_date) * [works\_count](https://docs.openalex.org/api-entities/publishers/publisher-object#works_count) Copy country_codes: ["DE"] Copy counts_by_year: [\ {\ year: 2021,\ works_count: 4211,\ cited_by_count: 120939\ },\ {\ year: 2020,\ works_count: 4363,\ cited_by_count: 119531\ },\ \ // and so forth\ ] Copy created_date: "2017-08-08" Copy display_name: "Elsevier BV" Copy hierarchy_level: 1 Copy id: "https://openalex.org/P4310320990" Copy ids: { openalex: "https://openalex.org/P4310320990", ror: "https://ror.org/02scfj030", wikidata: "https://www.wikidata.org/entity/Q746413" }, Copy image_thumbnail_url: "https://commons.wikimedia.org/w/index.php?title=Special:Redirect/file/MIT%20Press%20logo.svg&width=300" Copy image_url: "https://commons.wikimedia.org/w/index.php?title=Special:Redirect/file/MIT%20Press%20logo.svg" Copy id: "https://openalex.org/P4310321285", ... hierarchy_level: 2, lineage: [\ "https://openalex.org/P4310321285",\ "https://openalex.org/P4310319900",\ "https://openalex.org/P4310319965"\ ] Copy parent_publisher: "https://openalex.org/P4310311775" Copy roles: [\ {\ role: "funder",\ id: "https://openalex.org/F4320308380",\ works_count: 1004,\ },\ {\ role: "publisher",\ id: "https://openalex.org/P4310315589",\ works_count: 13986,\ },\ {\ role: "institution",\ id: "https://openalex.org/I32971472",\ works_count: 250031,\ }\ ] Copy sources_api_url: "https://api.openalex.org/sources?filter=host_organization.id:P4310319965" Copy summary_stats: { 2yr_mean_citedness: 5.065784263815827, h_index: 985, i10_index: 176682 } Copy updated_date: "2021-12-25T14:04:30.578837" Copy works_count: 13789818 --- # Filter funders | OpenAlex technical documentation You can filter funders with the `filter` parameter: * Get funders that are located in Canada [https://api.openalex.org/funders?filter=country\_code:ca](https://api.openalex.org/funders?filter=country_code:ca) It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query ### [](https://docs.openalex.org/api-entities/funders/filter-funders#funders-attribute-filters) `/funders` attribute filters You can filter using these attributes of the `Funder` entity object (click each one to view their documentation on the [`Funder`](https://docs.openalex.org/api-entities/funders/funder-object) object page): * [`cited_by_count`](https://docs.openalex.org/api-entities/funders/funder-object#cited_by_count) * [`country_code`](https://docs.openalex.org/api-entities/funders/funder-object#country_code) * [`grants_count`](https://docs.openalex.org/api-entities/funders/funder-object#grants_count) * [`ids.openalex`](https://docs.openalex.org/api-entities/funders/funder-object#ids) (alias: `openalex`) * [`ids.ror`](https://docs.openalex.org/api-entities/funders/funder-object#ids) (alias: `ror`) * [`ids.wikidata`](https://docs.openalex.org/api-entities/funders/funder-object#ids) (alias: `wikidata`) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/funders/funder-object#summary_stats) (accepts float, null, !null, can use range queries such as < >) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/funders/funder-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/funders/funder-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`works_count`](https://docs.openalex.org/api-entities/funders/funder-object#works_count) ### [](https://docs.openalex.org/api-entities/funders/filter-funders#funders-convenience-filters) `/funders` convenience filters These filters aren't attributes of the [`Funder`](https://docs.openalex.org/api-entities/funders/funder-object) object, but they're included to address some common use cases: #### [](https://docs.openalex.org/api-entities/funders/filter-funders#continent) `continent` Value: a String with a valid [continent filter](https://docs.openalex.org/api-entities/geo/continents#filter-by-continent) Returns: funders that are located in the chosen continent. * Get funders that are located in South America [`https://api.openalex.org/funders?filter=continent:south\_america`](https://api.openalex.org/funders?filter=continent:south_america) #### [](https://docs.openalex.org/api-entities/funders/filter-funders#default.search) `default.search` Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/funders/search-funders#search-funders) for Funders. #### [](https://docs.openalex.org/api-entities/funders/filter-funders#description.search) `description.search` Value: a search string Returns: funders with a [`description`](https://docs.openalex.org/api-entities/funders/funder-object#description) containing the given string; see the [search page](https://docs.openalex.org/api-entities/funders/search-funders#search-a-specific-field) for details. * Get funders with description containing "health": [`https://api.openalex.org/funders?filter=description.search:health`](https://api.openalex.org/funders?filter=description.search:health) #### [](https://docs.openalex.org/api-entities/funders/filter-funders#display_name.search) `display_name.search` Value: a search string Returns: funders with a [`display_name`](https://docs.openalex.org/api-entities/funders/funder-object#display_name) containing the given string; see the [search page](https://docs.openalex.org/api-entities/funders/search-funders#search-a-specific-field) for details. * Get funders with names containing "health": [`https://api.openalex.org/funders?filter=display_name.search:health`](https://api.openalex.org/funders?filter=display_name.search:health) In most cases, you should use the [`search` parameter](https://docs.openalex.org/api-entities/funders/search-funders) instead of this filter because it uses a better search algorithm. #### [](https://docs.openalex.org/api-entities/funders/filter-funders#is_global_south) `is_global_south` Value: a Boolean (`true` or `false`) Returns: funders that are located in the [Global South](https://docs.openalex.org/api-entities/geo/regions#global-south) . * Get funders that are located in the Global South [https://api.openalex.org/funders?filter=is\_global\_south:true](https://api.openalex.org/funders?filter=is_global_south:true) [PreviousGet lists of funders](https://docs.openalex.org/api-entities/funders/get-lists-of-funders) [NextSearch funders](https://docs.openalex.org/api-entities/funders/search-funders) Last updated 22 days ago * [/funders attribute filters](https://docs.openalex.org/api-entities/funders/filter-funders#funders-attribute-filters) * [/funders convenience filters](https://docs.openalex.org/api-entities/funders/filter-funders#funders-convenience-filters) --- # Sample entity lists | OpenAlex technical documentation You can use `sample` to get a random list of up to 10,000 results. * Get 100 random works [https://api.openalex.org/works?sample=100&per-page=100](https://api.openalex.org/works?sample=100&per-page=100) * Get 50 random works that are open access and published in 2021 [https://api.openalex.org/works?filter=open\_access.is\_oa:true,publication\_year:2021&sample=50&per-page=50](https://api.openalex.org/works?filter=open_access.is_oa:true,publication_year:2021&sample=50&per-page=50) You can add a `seed` value in order to retrieve the same set of random records, in the same order, multiple times. * Get 20 random sources with a seed value [https://api.openalex.org/sources?sample=20&seed=123](https://api.openalex.org/sources?sample=20&seed=123) Depending on your query, random results with a seed value _may_ change over time due to new records coming into OpenAlex. [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists#limitations) Limitations ----------------------------------------------------------------------------------------------------------------------- * The sample size is limited to 10,000 results. * You must provide a `seed` value when paging beyond the first page of results. Without a seed value, you might get duplicate records in your results. * You must use [basic paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#basic-paging) when sampling. Cursor pagination is not supported. [PreviousSelect fields](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) [NextAutocomplete entities](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) Last updated 22 days ago --- # Get a single concept | OpenAlex technical documentation These are the original OpenAlex Concepts, which are being deprecated in favor of [Topics](https://docs.openalex.org/api-entities/topics) . We will continue to provide these Concepts for Works, but we will not be actively maintaining, updating, or providing support for these concepts. Unless you have a good reason to be relying on them, we encourage you to look into [Topics](https://docs.openalex.org/api-entities/topics) instead. It's easy to get a concept from the API with: `/concepts/`. Here's an example: * Get the concept with the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) `C71924100`: [https://api.openalex.org/concepts/C71924100](https://api.openalex.org/concepts/C71924100) That will return a [`Concept`](https://docs.openalex.org/api-entities/concepts/concept-object) object, describing everything OpenAlex knows about the concept with that ID: Copy { "id": "https://openalex.org/C71924100", "wikidata": "https://www.wikidata.org/wiki/Q11190", "display_name": "Medicine", "level": 0, "description": "field of study for diagnosing, treating and preventing disease", // other fields removed for brevity } You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . ### [](https://docs.openalex.org/api-entities/concepts/get-a-single-concept#external-ids) External IDs You can look up concepts using external IDs such as a wikidata ID: * Get the concept with wikidata ID Q11190: [https://api.openalex.org/concepts/wikidata:Q11190](https://api.openalex.org/concepts/wikidata:Q11190) Available external IDs for concepts are: External ID URN Microsoft Academic Graph (MAG) `mag` Wikidata `wikidata` ### [](https://docs.openalex.org/api-entities/concepts/get-a-single-concept#select-fields) Select fields You can use `select` to limit the fields that are returned in a concept object. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` for a concept object [https://api.openalex.org/concepts/C71924100?select=id,display\_name](https://api.openalex.org/concepts/C71924100?select=id,display_name) [PreviousConcept object](https://docs.openalex.org/api-entities/concepts/concept-object) [NextGet lists of concepts](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts) Last updated 22 days ago * [External IDs](https://docs.openalex.org/api-entities/concepts/get-a-single-concept#external-ids) * [Select fields](https://docs.openalex.org/api-entities/concepts/get-a-single-concept#select-fields) --- # OpenAlex snapshot | OpenAlex technical documentation For most use cases, the REST API is your best option. However, you can also download ([instructions here](https://docs.openalex.org/download-all-data/download-to-your-machine) ) and install a complete copy of the OpenAlex database on your own server, using the database snapshot. The snapshot consists of seven files (split into smaller files for convenience), with one file for each of our seven entity types. The files are in the [JSON Lines](https://jsonlines.org/) format; each line is a JSON object, exactly the same as [you'd get from our API](https://docs.openalex.org/api-entities/works/get-a-single-work) . The properties of these JSON objects are documented in each entity's object section (for example, the [`Work`](https://docs.openalex.org/api-entities/works/work-object) object). The snapshot is updated about once per month; you can read [release notes for each new update here.](https://github.com/ourresearch/openalex-guts/blob/main/files-for-datadumps/standard-format/RELEASE_NOTES.txt) If you've worked with a dataset like this before, the [snapshot data format](https://docs.openalex.org/download-all-data/snapshot-data-format) may be all you need to get going. If not, read on. The rest of this guide will tell you how to (a) download the snapshot and (b) upload it to your own database. We’ll cover two general approaches: * Load the intact OpenAlex records to a data warehouse (we’ll use [BigQuery](https://cloud.google.com/bigquery) as an example) and use native JSON functions to query the [Work](https://docs.openalex.org/api-entities/works/work-object) , [Author](https://docs.openalex.org/api-entities/authors/author-object) , [Source](https://docs.openalex.org/api-entities/sources/source-object) , [Institution](https://docs.openalex.org/api-entities/institutions/institution-object) , [Concept](https://docs.openalex.org/api-entities/concepts/concept-object) , and [Publisher](https://docs.openalex.org/api-entities/publishers/publisher-object) objects directly. * Flatten the records into a normalized schema in a relational database (we’ll use [PostgreSQL](https://www.postgresql.org/) ) while preserving the relationships between objects. We'll assume you're initializing a fresh snapshot. To keep it up to date, you'll have to take the information from [Downloading updated Entities](https://docs.openalex.org/download-all-data/snapshot-data-format#downloading-updated-entities) and generalize from the steps in the guide. This is hard. Working with such a big and complicated dataset hardly ever goes according to plan. If it gets scary, try the [REST API](https://docs.openalex.org/how-to-use-the-api/api-overview) . In fact, try the REST API first. It can answer most of your questions and has a much lower barrier to entry. There’s more than one way to do everything. We’ve tried to pick one reasonable default way to do each step, so if something doesn’t work in your environment or with the tools you have available, let us know. Up next: the snapshot [data format](https://docs.openalex.org/download-all-data/snapshot-data-format) , [downloading the data](https://docs.openalex.org/download-all-data/download-to-your-machine) and [getting it into your database](https://docs.openalex.org/download-all-data/upload-to-your-database) . [PreviousRate limits and authentication](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication) [NextSnapshot data format](https://docs.openalex.org/download-all-data/snapshot-data-format) Last updated 22 days ago --- # Select fields | OpenAlex technical documentation You can use `select` to limit the fields that are returned in results. * Display works with only the `id`, `doi`, and `display_name` returned in the results [`https://api.openalex.org/works?select=id,doi,display\_name`](https://api.openalex.org/works?select=id,doi,display_name) Copy "results": [\ {\ "id": "https://openalex.org/W1775749144",\ "doi": "https://doi.org/10.1016/s0021-9258(19)52451-6",\ "display_name": "PROTEIN MEASUREMENT WITH THE FOLIN PHENOL REAGENT"\ },\ {\ "id": "https://openalex.org/W2100837269",\ "doi": "https://doi.org/10.1038/227680a0",\ "display_name": "Cleavage of Structural Proteins during the Assembly of the Head of Bacteriophage T4"\ },\ // more results removed for brevity\ ] [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields#limitations) Limitations ----------------------------------------------------------------------------------------------------------------- The fields you choose must exist within the entity (of course). You can only select root-level fields. So if we have a record like so: You can choose to display `id` and `open_access`, but you will get an error if you try to choose `open_access.is_oa`. You can use select fields when getting lists of entities or a [single entity](https://docs.openalex.org/how-to-use-the-api/get-single-entities/select-fields) . It does not work with [group-by](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) or [autocomplete](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) . [PreviousSort entity lists](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) [NextSample entity lists](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) Last updated 22 days ago Copy "id": "https://openalex.org/W2138270253", "open_access": { "is_oa": true, "oa_status": "bronze", "oa_url": "http://www.pnas.org/content/74/12/5463.full.pdf" } --- # Get lists of awards | OpenAlex technical documentation You can get lists of awards: * Get all awards in OpenAlex: [`https://api.openalex.org/awards`](https://api.openalex.org/awards) Which returns a response like this: Copy { meta: { count: 12345678, db_response_time_ms: 50, page: 1, per_page: 25, groups_count: null }, results: [\ // list of Award objects\ ] } [](https://docs.openalex.org/api-entities/awards/get-lists-of-awards#page-and-sort-awards) Page and sort awards -------------------------------------------------------------------------------------------------------------------- By default we return 25 results per page. You can change this default and [page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) through awards with the `per_page` and `page` parameters: * Get the second page of awards results, with 50 results per page: [`https://api.openalex.org/awards?per_page=50&page=2`](https://api.openalex.org/awards?per_page=50&page=2) You can [sort results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) with the `sort` parameter: * Sort awards by funded outputs count (highest first): [`https://api.openalex.org/awards?sort=funded_outputs_count:desc`](https://api.openalex.org/awards?sort=funded_outputs_count:desc) [](https://docs.openalex.org/api-entities/awards/get-lists-of-awards#sample-awards) Sample awards ------------------------------------------------------------------------------------------------------ You can use `sample` to get a random sample of awards. Read more about sampling and how to add a `seed` [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) . * Get a random sample of 10 awards: [`https://api.openalex.org/awards?sample=10`](https://api.openalex.org/awards?sample=10) [](https://docs.openalex.org/api-entities/awards/get-lists-of-awards#select-fields) Select fields ------------------------------------------------------------------------------------------------------ You can use `select` to limit the fields that are returned in a list of awards. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id` and `display_name` within awards results: [`https://api.openalex.org/awards?select=id,display_name`](https://api.openalex.org/awards?select=id,display_name) [PreviousGet a single award](https://docs.openalex.org/api-entities/awards/get-a-single-award) [NextFilter awards](https://docs.openalex.org/api-entities/awards/filter-awards) Last updated 22 days ago * [Page and sort awards](https://docs.openalex.org/api-entities/awards/get-lists-of-awards#page-and-sort-awards) * [Sample awards](https://docs.openalex.org/api-entities/awards/get-lists-of-awards#sample-awards) * [Select fields](https://docs.openalex.org/api-entities/awards/get-lists-of-awards#select-fields) --- # Get lists of concepts | OpenAlex technical documentation These are the original OpenAlex Concepts, which are being deprecated in favor of [Topics](https://docs.openalex.org/api-entities/topics) . We will continue to provide these Concepts for Works, but we will not be actively maintaining, updating, or providing support for these concepts. Unless you have a good reason to be relying on them, we encourage you to look into [Topics](https://docs.openalex.org/api-entities/topics) instead. You can get lists of concepts: * Get _all_ concepts in OpenAlex [https://api.openalex.org/concepts](https://api.openalex.org/concepts) Which returns a response like this: Copy { "meta": { "count": 65073, "db_response_time_ms": 26, "page": 1, "per_page": 25 }, "results": [\ {\ "id": "https://openalex.org/C41008148",\ "wikidata": "https://www.wikidata.org/wiki/Q21198",\ "display_name": "Computer science",\ // more fields (removed to save space)\ },\ {\ "id": "https://openalex.org/C71924100",\ "wikidata": "https://www.wikidata.org/wiki/Q11190",\ "display_name": "Medicine",\ // more fields (removed to save space)\ },\ // more results (removed to save space)\ ], "group_by": [] } [](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts#page-and-sort-concepts) Page and sort concepts ---------------------------------------------------------------------------------------------------------------------------- By default we return 25 results per page. You can change this default and [page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) through concepts with the `per-page` and `page` parameters: * Get the second page of concepts results, with 50 results returned per page [https://api.openalex.org/concepts?per-page=50&page=2](https://api.openalex.org/concepts?per-page=50&page=2) You also can [sort results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) with the `sort` parameter: * Sort concepts by cited by count, descending [https://api.openalex.org/concepts?sort=cited\_by\_count:desc](https://api.openalex.org/concepts?sort=cited_by_count:desc) Continue on to learn how you can [filter](https://docs.openalex.org/api-entities/concepts/filter-concepts) and [search](https://docs.openalex.org/api-entities/concepts/search-concepts) lists of concepts. [](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts#sample-concepts) Sample concepts -------------------------------------------------------------------------------------------------------------- You can use `sample` to get a random batch of concepts. Read more about sampling and how to add a `seed` value [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) . * Get 10 random concepts [https://api.openalex.org/concepts?sample=10](https://api.openalex.org/concepts?sample=10) [](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts#select-fields) Select fields ---------------------------------------------------------------------------------------------------------- You can use `select` to limit the fields that are returned in a list of concepts. More details are [here](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/select-fields) . * Display only the `id`, `display_name`, and `description` within concepts results [https://api.openalex.org/concepts?select=id,display\_name,description](https://api.openalex.org/concepts?select=id,display_name,description) [PreviousGet a single concept](https://docs.openalex.org/api-entities/concepts/get-a-single-concept) [NextFilter concepts](https://docs.openalex.org/api-entities/concepts/filter-concepts) Last updated 22 days ago * [Page and sort concepts](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts#page-and-sort-concepts) * [Sample concepts](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts#sample-concepts) * [Select fields](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts#select-fields) --- # FAQ | OpenAlex technical documentation ### [](https://docs.openalex.org/additional-help/faq#how-do-i-cite-openalex) How do I cite OpenAlex? See our [citation section here.](https://docs.openalex.org/#citation) ### [](https://docs.openalex.org/additional-help/faq#are-openalex-ids-stable) Are OpenAlex IDs stable? Yes!\* The work associated with ID W1234 will keep the ID W1234. When we find duplicated works, authors, etc that already have assigned IDs, we merge them. Merged entities will redirect to the proper entity in the API. In the data snapshot, there is a directory which lists the IDs that have been merged. \*In July 2023, OpenAlex switched to a [new, more accurate, author identification system](https://docs.openalex.org/api-entities/authors/author-disambiguation) , replaced all OpenAlex Author IDs with new ones. This is a very rare case in which we violate the rule of having stable IDs, which is needed to make the improvements. Old IDs and their connections to works remain available in the historical OpenAlex data. ### [](https://docs.openalex.org/additional-help/faq#can-you-index-my-journal) Can you index my journal? We automatically index new journals and articles so there is nothing you need to do. We primarily retrieve new records from [Crossref](https://www.crossref.org/) . So if you are not seeing your journal or article in OpenAlex, it is best to check if it is in Crossref with a query like `https://api.crossref.org/works/` ([example](https://api.crossref.org/works/10.1097/HS9.0000000000000014) ). We do not curate journals or limit which journals will be included in OpenAlex. So any discoverable journals will be added to the data set. If your example DOI is in Crossref but not in OpenAlex, please send us a [support request](https://openalex.org/help) so we can look into it further! ### [](https://docs.openalex.org/additional-help/faq#do-you-disambiguate-authors) Do you disambiguate authors? Yes. Using coauthors, references, and other features of the data, we can tell that the same Jane Smith wrote both "Frog behavior" and "Frogs: A retrospective," but it's a different Jane Smith who wrote "Oats before boats: The breakfast customs of 17th-Century Dutch bargemen." For more details on this, see the page on [Author Disambiguation](https://help.openalex.org/hc/en-us/articles/24347048891543-Author-disambiguation) . ### [](https://docs.openalex.org/additional-help/faq#do-you-gather-author-affiliations) Do you gather author affiliations? Yes. We automatically gather and normalize author affiliations from both structured and unstructured sources. ### [](https://docs.openalex.org/additional-help/faq#where-does-your-data-come-from) Where does your data come from? OpenAlex is not doing this alone! Rather, we're aggregating and standardizing data from a whole bunch of other great projects, like a river fed by many tributaries. Our two most important data sources are [MAG](https://aka.ms/msracad) and [Crossref.](https://www.crossref.org/) Other key sources include: * [ORCID](https://orcid.org/) * [ROR](https://ror.org/) * [DOAJ](https://doaj.org/) * [Unpaywall](https://unpaywall.org/) * [Pubmed](https://pubmed.ncbi.nlm.nih.gov/) * [Pubmed Central](https://www.ncbi.nlm.nih.gov/pmc/) * [The ISSN International Centre](https://www.issn.org/) * [Internet Archive](https://archive.org/details/GeneralIndex) * Web crawls * Subject-area and institutional repositories from [arXiv](https://arxiv.org/) to [Zenodo](https://zenodo.org/) and everywhere in between Learn more at our general help center article: [About the data](https://help.openalex.org/hc/en-us/articles/24397285563671-About-the-data) ### [](https://docs.openalex.org/additional-help/faq#how-often-is-the-data-updated) How often is the data updated? For now, the database snapshot is updated about once per month. We also offer a much faster update cadence—as often as once every few hours—through [OpenAlex Premium.](https://openalex.org/pricing) ### [](https://docs.openalex.org/additional-help/faq#is-your-data-quality-better-than) Is your data quality better than \_\_\_\_? Our dataset is still very young, so there's not a lot of systematic research comparing OpenAlex to peer databases like MAG, Scopus, Dimensions, etc. We're currently working on publishing some research like that ourselves. Our initial finding are very encouraging...we believe OpenAlex is already comparable in coverage and accuracy to the more established players--but OpenAlex is 100% open data, built on 100% open-source code. We think that's a really important feature. We will also continue improving the data quality in the days, weeks, months, and years ahead! ### [](https://docs.openalex.org/additional-help/faq#how-is-openalex-licensed) How is OpenAlex licensed? OpenAlex data is licensed as [CC0](https://creativecommons.org/publicdomain/zero/1.0/) so it is free to use and distribute. ### [](https://docs.openalex.org/additional-help/faq#how-much-does-openalex-cost) How much does OpenAlex cost? It's free! The [website](https://explore.openalex.org/) , the [API](https://docs.openalex.org/) , and the [database snapshot](https://docs.openalex.org/download-all-data/openalex-snapshot) are all available at no charge. As a nonprofit, making this data free and open is part of our mission. For those who would like a higher level of service and to provide direct financial support for our mission, we offer [OpenAlex Premium. Click here to learn more.](https://openalex.org/pricing) ### [](https://docs.openalex.org/additional-help/faq#ive-noticed-incorrect-data-in-an-openalex-author-profile.-how-can-i-correct-it) I've noticed incorrect data in an OpenAlex author profile. How can I correct it? Please see the help section on [Author profile curation](https://help.openalex.org/hc/en-us/articles/27283405287319-How-can-I-fix-errors-in-an-OpenAlex-author-profile) . ### [](https://docs.openalex.org/additional-help/faq#whats-your-sustainability-plan) What's your sustainability plan? Our nonprofit (OurResearch) has a ten-year track record of building sustainable scholarly infrastructure, and a formal commitment to sustainability as part of [our adoption of the POSI principles.](https://blog.ourresearch.org/posi/) We're currently still exploring our options for OpenAlex's sustainability plan. Thanks to a generous grant from [Arcadia](https://www.arcadiafund.org.uk/) , we've got lots of runway, and we don't need to roll anything out in a rush. Our Unpaywall project (a free index of the world's open-access research literature) has been self-sustaining via a freemium revenue model for nearly five years, and we have recently introduced a similar model in [OpenAlex Premium.](https://openalex.org/pricing) Access to the data will always be free for everyone, but OpenAlex Premium offers several benefits in service above the services we offer for free. ### [](https://docs.openalex.org/additional-help/faq#i-have-a-question-about-the-openalexr-library.-could-you-help-me) I have a question about the openalexR library. Could you help me? The [openalexR](https://docs.ropensci.org/openalexR/) package is a great way to work with the OpenAlex API using the R programming language, but it is third-party software that we do not maintain ourselves. Please direct any questions you have to them instead. ### [](https://docs.openalex.org/additional-help/faq#how-can-i-count-self-citations-between-works) How can I count self-citations between works? If you want to count self-citations—or, inversely independent citations where citing and the cited work do not have any authors in common—you can check each citation for whether they share any Author IDs in common in their [`authorships`](https://docs.openalex.org/api-entities/works/work-object/authorship-object) field. See [here](https://docs.openalex.org/api-entities/works/work-object#authorships) for more information. ### [](https://docs.openalex.org/additional-help/faq#do-you-provide-access-to-full-text-papers) Do you provide access to full-text papers? We provide links to the full-text PDFs for open-access works whenever possible. In addition, we have access to raw full-text for many works either through PDF parsing we have done, or using the Internet Archive's general index, which we use to power our [search](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) . You can learn more about this [here](https://docs.openalex.org/api-entities/works/work-object#has_fulltext) . We do not currently offer direct access to raw full-text through the API or data snapshot. [PreviousReport bugs](https://docs.openalex.org/additional-help/report-bugs) Last updated 22 days ago * [How do I cite OpenAlex?](https://docs.openalex.org/additional-help/faq#how-do-i-cite-openalex) * [Are OpenAlex IDs stable?](https://docs.openalex.org/additional-help/faq#are-openalex-ids-stable) * [Can you index my journal?](https://docs.openalex.org/additional-help/faq#can-you-index-my-journal) * [Do you disambiguate authors?](https://docs.openalex.org/additional-help/faq#do-you-disambiguate-authors) * [Do you gather author affiliations?](https://docs.openalex.org/additional-help/faq#do-you-gather-author-affiliations) * [Where does your data come from?](https://docs.openalex.org/additional-help/faq#where-does-your-data-come-from) * [How often is the data updated?](https://docs.openalex.org/additional-help/faq#how-often-is-the-data-updated) * [Is your data quality better than \_\_\_\_?](https://docs.openalex.org/additional-help/faq#is-your-data-quality-better-than) * [How is OpenAlex licensed?](https://docs.openalex.org/additional-help/faq#how-is-openalex-licensed) * [How much does OpenAlex cost?](https://docs.openalex.org/additional-help/faq#how-much-does-openalex-cost) * [I've noticed incorrect data in an OpenAlex author profile. How can I correct it?](https://docs.openalex.org/additional-help/faq#ive-noticed-incorrect-data-in-an-openalex-author-profile.-how-can-i-correct-it) * [What's your sustainability plan?](https://docs.openalex.org/additional-help/faq#whats-your-sustainability-plan) * [I have a question about the openalexR library. Could you help me?](https://docs.openalex.org/additional-help/faq#i-have-a-question-about-the-openalexr-library.-could-you-help-me) * [How can I count self-citations between works?](https://docs.openalex.org/additional-help/faq#how-can-i-count-self-citations-between-works) * [Do you provide access to full-text papers?](https://docs.openalex.org/additional-help/faq#do-you-provide-access-to-full-text-papers) --- # Paging | OpenAlex technical documentation You can see executable examples of paging in [this user-contributed Jupyter notebook!](https://github.com/ourresearch/openalex-api-tutorials/blob/main/notebooks/getting-started/paging.ipynb) ### [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#basic-paging) Basic paging Use the `page` query parameter to control which page of results you want (eg `page=1`, `page=2`, etc). By default there are 25 results per page; you can use the `per-page` parameter to change that to any number between 1 and 200. * Get the 2nd page of a list: [`https://api.openalex.org/works?page=2`](https://api.openalex.org/works?page=2) * Get 200 results on the second page: [`https://api.openalex.org/works?page=2&per-page=200`](https://api.openalex.org/works?page=2&per-page=200) Basic paging only works to get the first 10,000 results of any list. If you want to see more than 10,000 results, you'll need to use [cursor paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#cursor-paging) . ### [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#cursor-paging) Cursor paging Cursor paging is a bit more complicated than [basic paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#basic-paging) , but it allows you to access as many records as you like. To use cursor paging, you request a cursor by adding the `cursor=*` parameter-value pair to your query. * Get a cursor in order to start cursor pagination: [`https://api.openalex.org/works?filter=publication_year:2020&per-page=100&cursor=*`](https://api.openalex.org/works?filter=publication_year:2020&per-page=100&cursor=*) The response to your query will include a `next_cursor` value in the response's `meta` object. Here's what it looks like: Copy { "meta": { "count": 8695857, "db_response_time_ms": 28, "page": null, "per_page": 100, "next_cursor": "IlsxNjA5MzcyODAwMDAwLCAnaHR0cHM6Ly9vcGVuYWxleC5vcmcvVzI0ODg0OTk3NjQnXSI=" }, "results" : [\ // the first page of results\ ] } To retrieve the next page of results, copy the `meta.next_cursor` value into the cursor field of your next request. * Get the next page of results using a cursor value: [`https://api.openalex.org/works?filter=publication_year:2020&per-page=100&cursor=IlsxNjA5MzcyODAwMDAwLCAnaHR0cHM6Ly9vcGVuYWxleC5vcmcvVzI0ODg0OTk3NjQnXSI=`](https://api.openalex.org/works?filter=publication_year:2020&per-page=100&cursor=IlsxNjA5MzcyODAwMDAwLCAnaHR0cHM6Ly9vcGVuYWxleC5vcmcvVzI0ODg0OTk3NjQnXSI=) This second page of results will have a new value for `meta.next_cursor`. You'll use this new value the same way you did the first, and it'll give you the second page of results. To get _all_ the results, keep repeating this process until `meta.next_cursor` is null and the `results` set is empty. Besides using cursor paging to get entities, you can also use it in [`group_by` queries](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) . **Don't use cursor paging to download the whole dataset.** * It's bad for you because it will take many days to page through a long list like /works or /authors. * It's bad for us (and other users!) because it puts a massive load on our servers. Instead, download everything at once, using the [OpenAlex snapshot](https://docs.openalex.org/download-all-data/openalex-snapshot) . It's free, easy, fast, and you get all the results in same format you'd get from the API. [PreviousGet lists of entities](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities) [NextFilter entity lists](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) Last updated 22 days ago * [Basic paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#basic-paging) * [Cursor paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#cursor-paging) --- # Concept object | OpenAlex technical documentation These are the original OpenAlex Concepts, which are being deprecated in favor of [Topics](https://docs.openalex.org/api-entities/topics) . We will continue to provide these Concepts for Works, but we will not be actively maintaining, updating, or providing support for these concepts. Unless you have a good reason to be relying on them, we encourage you to look into [Topics](https://docs.openalex.org/api-entities/topics) instead. These are the fields in a concept object. When you use the API to get a [single concept](https://docs.openalex.org/api-entities/concepts/get-a-single-concept) or [lists of concepts](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts) , this is what's returned. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#ancestors) `ancestors` _List:_ List of concepts that this concept descends from, as [dehydrated Concept](https://docs.openalex.org/api-entities/concepts/concept-object#the-dehydratedconcept-object) objects. See the [concept tree section](https://docs.openalex.org/api-entities/concepts) for more details on how the different layers of concepts work together. Copy ancestors: [\ {\ id: "https://openalex.org/C2522767166",\ wikidata: "https://www.wikidata.org/wiki/Q2374463",\ display_name: "Data science",\ level: 1\ },\ {\ id: "https://openalex.org/C161191863",\ wikidata: "https://www.wikidata.org/wiki/Q199655",\ display_name: "Library science",\ level: 1\ },\ \ // and so forth\ ] ### [](https://docs.openalex.org/api-entities/concepts/concept-object#cited_by_count) `cited_by_count` _Integer:_ The number citations to works that have been tagged with this concept. Or less formally: the number of citations to this concept. For example, if there are just two works tagged with this concept and one of them has been cited 10 times, and the other has been cited 1 time, `cited_by_count` for this concept would be `11`. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#counts_by_year) `counts_by_year` _List:_ The values of [`works_count`](https://docs.openalex.org/api-entities/concepts/concept-object#works_count) and [`cited_by_count`](https://docs.openalex.org/api-entities/concepts/concept-object#cited_by_count) for _each_ of the last ten years, binned by year. To put it another way: for every listed year, you can see how many new works were tagged with this concept, and how many times _any_ work tagged with this concept got cited. Years with zero citations and zero works have been removed so you will need to add those back in if you need them. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#created_date) `created_date` _String:_ The date this `Concept` object was created in the OpenAlex dataset, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#description) `description` _String:_ A brief description of this concept. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#display_name) `display_name` _String:_ The English-language label of the concept. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#id) `id` _String:_ The OpenAlex ID for this concept. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#ids) `ids` _Object:_ All the external identifiers that we know about for this concept. IDs are expressed as URIs whenever possible. Possible ID types: * `mag` (_Integer:_ this concept's [Microsoft Academic Graph](https://www.microsoft.com/en-us/research/project/microsoft-academic-graph/) ID) * `openalex` (_String:_ this concept's [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) . Same as [`Concept.id`](https://docs.openalex.org/api-entities/concepts/concept-object#id) ) * `umls_cui` (_List:_ this concept's [Unified Medical Language System](https://www.nlm.nih.gov/research/umls/index.html) [Concept Unique Identifiers](https://www.nlm.nih.gov/research/umls/new_users/online_learning/Meta_005.html) ) * `umls_aui` (_List:_ this concept's [Unified Medical Language System](https://www.nlm.nih.gov/research/umls/index.html) [Atom Unique Identifiers](https://www.nlm.nih.gov/research/umls/new_users/online_learning/Meta_005.html) ) * `wikidata` (_String:_ this concept's [Wikidata ID](https://www.wikidata.org/wiki/Wikidata:Identifiers) . Same as [`Concept.wikidata`](https://docs.openalex.org/api-entities/concepts/concept-object#wikidata) ) * `wikipedia` (_String:_ this concept's Wikipedia page URL) Many concepts are missing one or more ID types (either because we don't know the ID, or because it was never assigned). Keys for null IDs are not displayed.. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#image_thumbnail_url) `image_thumbnail_url` _String:_ Same as [`image_url`](https://docs.openalex.org/api-entities/concepts/concept-object#image_url) , but it's a smaller image. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#image_url) `image_url` _String:_ URL where you can get an image representing this concept, where available. Usually this is hosted on Wikipedia. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#international) `international` _Object:_ This concept's display name in many languages, derived from article titles on each language's wikipedia. See the [Wikidata entry](https://www.wikidata.org/wiki/Q137496#sitelinks-wikipedia) for "Java Bytecode" for example source data. * `display_name` (_Object_) * `key` (String): language code in [wikidata language code](https://www.wikidata.org/wiki/Property:P9753) format. Full list of languages is [here](https://doc.wikimedia.org/mediawiki-core/master/php/Names_8php_source.html) . * `value` (String): `display_name` in the given language ### [](https://docs.openalex.org/api-entities/concepts/concept-object#level) `level` _Integer:_ The level in the concept tree where this concept lives. Lower-level concepts are more general, and higher-level concepts are more specific. [Computer Science](https://openalex.org/C41008148) has a level of 0; [Java Bytecode](https://openalex.org/C2777472213) has a level of 5. Level 0 concepts have no ancestors and level 5 concepts have no descendants. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#related_concepts) `related_concepts` _List:_ Concepts that are similar to this one. Each listed concept is a [dehydrated Concept](https://docs.openalex.org/api-entities/concepts/concept-object#the-dehydratedconcept-object) object, with one additional attribute: * `score` (_Float_): The strength of association between this concept and the listed concept, on a scale of 0-100. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#summary_stats) `summary_stats` _Object:_ Citation metrics for this concept * `2yr_mean_citedness` _Float_: The 2-year mean citedness for this source. Also known as [impact factor](https://en.wikipedia.org/wiki/Impact_factor) . We use the year prior to the current year for the citations (the numerator) and the two years prior to that for the citation-receiving publications (the denominator). * `h_index` _Integer_: The [_h_\-index](https://en.wikipedia.org/wiki/H-index) for this concept. * `i10_index` _Integer_: The [i-10 index](https://en.wikipedia.org/wiki/Author-level_metrics#i-10-index) for this concept. While the _h_\-index and the i-10 index are normally author-level metrics and the 2-year mean citedness is normally a journal-level metric, they can be calculated for any set of papers, so we include them for concepts. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#updated_date) `updated_date` _String:_ The last time anything in this concept object changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. This date is updated for _any change at all_, including increases in various counts. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#wikidata) `wikidata` _String:_ The [Wikidata ID](https://www.wikidata.org/wiki/Wikidata:Identifiers) for this concept. This is the [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for concepts. _All_ OpenAlex concepts have a Wikidata ID, because all OpenAlex concepts are also Wikidata concepts. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#works_api_url) `works_api_url` _String:_ An URL that will get you a list of all the works tagged with this concept. We express this as an API URL (instead of just listing the works themselves) because there might be millions of works tagged with this concept, and that's too many to fit here. ### [](https://docs.openalex.org/api-entities/concepts/concept-object#works_count) `works_count` _Integer:_ The number of works tagged with this concept. [](https://docs.openalex.org/api-entities/concepts/concept-object#the-dehydratedconcept-object) The `DehydratedConcept` object ----------------------------------------------------------------------------------------------------------------------------------- The `DehydratedConcept` is stripped-down [`Concept`](https://docs.openalex.org/api-entities/concepts/concept-object#the-concept-object) object, with most of its properties removed to save weight. Its only remaining properties are: * ``[`display_name`](concept-object.md#display\_name)`` * ``[`id`](concept-object.md#id)`` * ``[`level`](concept-object.md#level)`` * ``[`wikidata`](concept-object.md#wikidata)`` [PreviousConcepts](https://docs.openalex.org/api-entities/concepts) [NextGet a single concept](https://docs.openalex.org/api-entities/concepts/get-a-single-concept) Last updated 22 days ago * [ancestors](https://docs.openalex.org/api-entities/concepts/concept-object#ancestors) * [cited\_by\_count](https://docs.openalex.org/api-entities/concepts/concept-object#cited_by_count) * [counts\_by\_year](https://docs.openalex.org/api-entities/concepts/concept-object#counts_by_year) * [created\_date](https://docs.openalex.org/api-entities/concepts/concept-object#created_date) * [description](https://docs.openalex.org/api-entities/concepts/concept-object#description) * [display\_name](https://docs.openalex.org/api-entities/concepts/concept-object#display_name) * [id](https://docs.openalex.org/api-entities/concepts/concept-object#id) * [ids](https://docs.openalex.org/api-entities/concepts/concept-object#ids) * [image\_thumbnail\_url](https://docs.openalex.org/api-entities/concepts/concept-object#image_thumbnail_url) * [image\_url](https://docs.openalex.org/api-entities/concepts/concept-object#image_url) * [international](https://docs.openalex.org/api-entities/concepts/concept-object#international) * [level](https://docs.openalex.org/api-entities/concepts/concept-object#level) * [related\_concepts](https://docs.openalex.org/api-entities/concepts/concept-object#related_concepts) * [summary\_stats](https://docs.openalex.org/api-entities/concepts/concept-object#summary_stats) * [updated\_date](https://docs.openalex.org/api-entities/concepts/concept-object#updated_date) * [wikidata](https://docs.openalex.org/api-entities/concepts/concept-object#wikidata) * [works\_api\_url](https://docs.openalex.org/api-entities/concepts/concept-object#works_api_url) * [works\_count](https://docs.openalex.org/api-entities/concepts/concept-object#works_count) * [The DehydratedConcept object](https://docs.openalex.org/api-entities/concepts/concept-object#the-dehydratedconcept-object) Copy cited_by_count: 20248 Copy counts_by_year: [\ {\ year: 2021,\ works_count: 4211,\ cited_by_count: 120939\ },\ {\ year: 2020,\ works_count: 4363,\ cited_by_count: 119531\ },\ \ // and so forth\ ] Copy created_date: "2017-08-08" Copy description: "study of alternative metrics for analyzing and informing scholarship" Copy display_name: "Altmetrics" Copy id: "https://openalex.org/C2778407487" Copy ids: { openalex: "https://openalex.org/C2778407487", wikidata: "https://www.wikidata.org/wiki/Q14565201", wikipedia: "https://en.wikipedia.org/wiki/Altmetrics", mag: 2778407487 } Copy image_thumbnail_url: "https://upload.wikimedia.org/wikipedia/commons/thumb/f/f1/Altmetrics.svg/100px-Altmetrics.svg.png" Copy image_url: "https://upload.wikimedia.org/wikipedia/commons/f/f1/Altmetrics.svg" Copy international: { display_name: { ca: "Altmetrics", ... } } Copy level: 2 Copy related_concepts: [\ {\ id: "https://openalex.org/C2778793908",\ wikidata: null,\ display_name: "Citation impact",\ level: 3,\ score: 4.56749\ },\ {\ id: "https://openalex.org/C2779455604",\ wikidata: null,\ display_name: "Impact factor",\ level: 2,\ score: 4.46396\ }\ \ // and so forth\ ] Copy summary_stats: { 2yr_mean_citedness: 1.5295340589458237, h_index: 105, i10_index: 5045 } Copy updated_date: "2021-12-25T14:04:30.578837" Copy wikidata: "https://www.wikidata.org/wiki/Q14565201" Copy works_api_url: "https://api.openalex.org/works?filter=concept.id:C2778407487" Copy works_count: 3078 --- # Search entities | OpenAlex technical documentation [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#the-search-parameter) The `search` parameter --------------------------------------------------------------------------------------------------------------------------------------- The `search` query parameter finds results that match a given text search. Example: * Get works with search term "dna" in the title, abstract, or fulltext: [`https://api.openalex.org/works?search=dna`](https://api.openalex.org/works?search=dna) When you [search `works`](https://docs.openalex.org/api-entities/works/search-works) , the API looks for matches in titles, abstracts, and [fulltext](https://docs.openalex.org/api-entities/works/work-object#has_fulltext) . When you [search `concepts`](https://docs.openalex.org/api-entities/concepts/search-concepts) , we look in each concept's `display_name` and `description` fields. When you [search `sources`](https://docs.openalex.org/api-entities/sources/search-sources) , we look at the `display_name`_,_ `alternate_titles`, and `abbreviated_title` fields. When you [search `authors`](https://docs.openalex.org/api-entities/authors/search-authors) , we look at the `display_name` and `display_name_alternatives` fields. When you [search `institutions`](https://docs.openalex.org/api-entities/institutions/search-institutions) , we look at the `display_name`, `display_name_alternatives`, and `display_name_acronyms` fields. For most text search we remove [stop words](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-stop-tokenfilter.html) and use [stemming](https://en.wikipedia.org/wiki/Stemming) (specifically, the [Kstem token filter](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-kstem-tokenfilter.html) ) to improve results. So words like "the" and "an" are transparently removed, and a search for "possums" will also return records using the word "possum." With the exception of raw affiliation strings, we do not search within words but rather try to match whole words. So a search with "lun" will not match the word "lunar". ### [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#search-without-stemming) Search without stemming To disable stemming and the removal of stop words for searches on titles and abstracts, you can add `.no_stem` to the search filter. So, for example, if you want to search for "surgery" and not get "surgeries" too: * [`https://api.openalex.org/works?filter=display_name.search.no_stem:surgery`](https://api.openalex.org/works?filter=display_name.search.no_stem:surgery) * [`https://api.openalex.org/works?filter=title.search.no_stem:surgery`](https://api.openalex.org/works?filter=title.search.no_stem:surgery) * [`https://api.openalex.org/works?filter=abstract.search.no_stem:surgery`](https://api.openalex.org/works?filter=abstract.search.no_stem:surgery) * [`https://api.openalex.org/works?filter=title_and_abstract.search.no_stem:surgery`](https://api.openalex.org/works?filter=title_and_abstract.search.no_stem:surgery) ### [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#boolean-searches) Boolean searches Including any of the words `AND`, `OR`, or `NOT` in any of your searches will enable boolean search. Those words must be UPPERCASE. You can use this in all searches, including using the `search` parameter, and using [search filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#the-search-filter) . This allows you to craft complex queries using those boolean operators along with parentheses and quotation marks. Surrounding a phrase with quotation marks will search for an exact match of that phrase, after stemming and stop-word removal (be sure to use **double quotation marks** — `"`). Using parentheses will specify order of operations for the boolean operators. Words that are not separated by one of the boolean operators will be interpreted as `AND`. Behind the scenes, the boolean search is using Elasticsearch's [query string query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html) on the searchable fields (such as title, abstract, and fulltext for works; see each individual entity page for specifics about that entity). Wildcard and fuzzy searches using `*`, `?` or `~` are not allowed; these characters will be removed from any searches. These searches, even when using quotation marks, will go through the same cleaning as desscribed above, including stemming and removal of stop words. * Search for works that mention "elmo" and "sesame street," but not the words "cookie" or "monster": [`https://api.openalex.org/works?search=(elmo AND "sesame street") NOT (cookie OR monster)`](https://api.openalex.org/works?search=%28elmo%20AND%20%22sesame%20street%22%29%20NOT%20%28cookie%20OR%20monster%29) [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#relevance-score) Relevance score --------------------------------------------------------------------------------------------------------------------------- When you use search, each returned entity in the results lists gets an extra property called `relevance_score`, and the list is by default sorted in descending order of `relevance_score`. The `relevance_score` is based on text similarity to your search term. It also includes a weighting term for citation counts: more highly-cited entities score higher, all else being equal. If you search for a multiple-word phrase, the algorithm will treat each word separately, and rank results higher when the words appear close together. If you want to return only results where the exact phrase is used, just enclose your phrase within quotes. Example: * Get works with the exact phrase "fierce creatures" in the title or abstract (returns just a few results): [`https://api.openalex.org/works?search="fierce%20creatures"`](https://api.openalex.org/works?search=%22fierce%20creatures%22) * Get works with the words "fierce" and "creatures" in the title or abstract, with works that have the two words close together ranked higher by `relevance_score` (returns way more results): [`https://api.openalex.org/works?search=fierce%20creatures`](https://api.openalex.org/works?search=fierce%20creatures) [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#the-search-filter) The search filter ------------------------------------------------------------------------------------------------------------------------------- You can also use search as a [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) , allowing you to fine-tune the fields you're searching over. To do this, you append `.search` to the end of the property you are filtering for: * Get authors who have "Einstein" as part of their name: [`https://api.openalex.org/authors?filter=display_name.search:einstein`](https://api.openalex.org/authors?filter=display_name.search:einstein) * Get works with "cubist" in the title: [`https://api.openalex.org/works?filter=title.search:cubist`](https://api.openalex.org/works?filter=title.search:cubist) Additionally, the filter `default.search` is available on all entities; this works the same as the [`search` parameter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#the-search-parameter) . You might be tempted to use the search filter to power an autocomplete or typeahead. Instead, we recommend you use the [autocomplete endpoint](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) , which is much faster. 👎 [`https://api.openalex.org/institutions?filter=display_name.search:florida`](https://api.openalex.org/institutions?filter=display_name.search:florida) 👍 [`https://api.openalex.org/autocomplete/institutions?q=Florida`](https://api.openalex.org/autocomplete/institutions?q=Florida) [PreviousFilter entity lists](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) [NextSort entity lists](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sort-entity-lists) Last updated 22 days ago * [The search parameter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#the-search-parameter) * [Search without stemming](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#search-without-stemming) * [Boolean searches](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#boolean-searches) * [Relevance score](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#relevance-score) * [The search filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities#the-search-filter) --- # Autocomplete entities | OpenAlex technical documentation The autocomplete endpoint lets you add autocomplete or typeahead components to your applications, without the overhead of hosting your own API endpoint. Each endpoint takes a string, and (very quickly) returns a list of entities that match that string. Here's an example of an autocomplete component that lets users quickly select an institution: ![](https://docs.openalex.org/~gitbook/image?url=https%3A%2F%2Fi.imgur.com%2Ff8yyWCd.png&width=768&dpr=4&quality=100&sign=b213c6c5&sv=2) A user looking for information on the flagship of Florida's state university system. This is the query behind that result: [`https://api.openalex.org/autocomplete/institutions?q=flori`](https://api.openalex.org/autocomplete/institutions?q=flori) The autocomplete endpoint is very fast; queries generally return in around 200ms. If you'd like to see it in action, we're using a slightly-modified version of this endpoint in the OpenAlex website here: [https://explore.openalex.org/](https://explore.openalex.org/) [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#request-format) Request format ------------------------------------------------------------------------------------------------------------------------------- The format for requests is simple: `/autocomplete/?q=` * `entity_type` (optional): the name of one of the OpenAlex entities: `works`, `authors`, `sources`, `institutions`, `concepts`, `publishers`, or `funders`. * `query`: the search string supplied by the user. You can optionally [filter autocomplete results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#filter-autocomplete-results) . [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#response-format) Response format --------------------------------------------------------------------------------------------------------------------------------- Each request returns a response object with two properties: * `meta`: an object with information about the request, including timing and results count * `results`: a list of up to ten results for the query, sorted by citation count. Each result represents an entity that matched against the query. Each object in the `results` list includes these properties: * `id` (string): The [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for this result entity. * `external_id` (string): The [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for this result entity. * `display_name` (string): The entity's `display_name` property. * `entity_type` (string): The entity's type: `author`, `concept`, `institution`, `source`, `publisher`, `funder`, or `work`. * `cited_by_count` (integer): The entity's `cited_by_count` property. For works this is simply the number of incoming citations. For other entities, it's the _sum_ of incoming citations for all the works linked to that entity. * `works_count` (integer): The number of works associated with the entity. For entity type `work` it's always null. * `hint`: Some extra information that can help identify the right item. Differs by entity type. ### [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#the-hint-property) The `hint` property Result objects have a `hint` property. You can show this to users to help them identify which item they're selecting. This is particularly helpful when the `display_name` values of different results are the same, as often happens when autocompleting an author entity--a user who types in `John Smi` is going to see a lot of identical-looking results, even though each one is a different person. The content of the `hint` property varies depending on what kind of entity you're looking up: * `Work`: The work's authors' display names, concatenated. e.g. "R. Alexander Pyron, John J. Wiens" * `Author`: The author's [last known institution](https://docs.openalex.org/api-entities/authors/author-object#last_known_institution) , e.g. "University of North Carolina at Chapel Hill, USA" * `Source`: The `host_organization`, e.g. "Oxford University Press" * `Institution`: The institution's location, e.g. "Gainesville, USA" * `Concept`: The Concept's [description](https://docs.openalex.org/api-entities/concepts/concept-object#description) , e.g. "the study of relation between plant species and genera" [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#ids-in-autocomplete) IDs in autocomplete ----------------------------------------------------------------------------------------------------------------------------------------- [Canonical External IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) and [OpenAlex IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) are detected within autocomplete queries and matched to the appropriate record if it exists. For example: * The query [`https://api.openalex.org/autocomplete?q=https://orcid.org/0000-0002-7436-3176`](https://api.openalex.org/autocomplete?q=https://orcid.org/0000-0002-7436-3176) will search for the author with ORCID ID `https://orcid.org/0000-0002-7436-3176` and return 0 records if it does not exist. * The query [`https://api.openalex.org/autocomplete/sources?q=S49861241`](https://api.openalex.org/autocomplete/sources?q=S49861241) will search for the source with OpenAlex ID `https://openalex.org/S49861241` and return 0 records if it does not exist. [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#filter-autocomplete-results) Filter autocomplete results --------------------------------------------------------------------------------------------------------------------------------------------------------- All entity [filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) and [search](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) queries can be added to autocomplete and work as expected, like: [`https://api.openalex.org/autocomplete/works?filter=publication_year:2010&search=frogs&q=greenhou`](https://api.openalex.org/autocomplete/works?filter=publication_year:2010&search=frogs&q=greenhou) [PreviousSample entity lists](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/sample-entity-lists) [NextGet groups of entities](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities) Last updated 22 days ago * [Request format](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#request-format) * [Response format](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#response-format) * [The hint property](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#the-hint-property) * [IDs in autocomplete](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#ids-in-autocomplete) * [Filter autocomplete results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities#filter-autocomplete-results) Copy { meta: { count: 183, db_response_time_ms: 5, page: 1, per_page: 10 }, results: [\ {\ id: "https://openalex.org/I33213144",\ display_name: "University of Florida",\ hint: "Gainesville, USA",\ cited_by_count: 17190001,\ entity_type: "institution",\ external_id: "https://ror.org/02y3ad647"\ },\ // more results...\ ] } --- # Snapshot data format | OpenAlex technical documentation Here are the details on where the OpenAlex data lives and how it's structured. * All the data is stored in [Amazon S3](https://aws.amazon.com/s3/) , in the [`openalex`](https://openalex.s3.amazonaws.com/browse.html) bucket. * The data files are gzip-compressed [JSON Lines](https://jsonlines.org/) , one row per entity. * The bucket contains one prefix (folder) for each entity type: [work](https://openalex.s3.amazonaws.com/browse.html#data/works/) , [author](https://openalex.s3.amazonaws.com/browse.html#data/authors/) , [source](https://openalex.s3.amazonaws.com/browse.html#data/sources/) , [institution](https://openalex.s3.amazonaws.com/browse.html#data/institutions/) , [concept](https://openalex.s3.amazonaws.com/browse.html#data/concepts/) , and [publisher](https://openalex.s3.amazonaws.com/browse.html#data/publishers/) . * Records are partitioned by [updated\_date](https://docs.openalex.org/api-entities/works/work-object#updated_date) . Within each entity type prefix, each object (file) is further prefixed by this date. For example, if an [`Author`](https://docs.openalex.org/api-entities/authors/author-object) has an updated\_date of 2021-12-30 it will be prefixed`/data/authors/updated_date=2021-12-30/`. * If you're initializing a fresh snapshot, the `updated_date` partitions aren't important yet. You need all the entities, so for `Authors` you would get [`/data/authors`](https://openalex.s3.amazonaws.com/browse.html#data/authors/) `/*/*.gz` * There are multiple objects under each `updated_date` partition. Each is under 2GB. * The manifest file is JSON (in [redshift manifest](https://docs.aws.amazon.com/redshift/latest/dg/loading-data-files-using-manifest.html) format) and lists all the data files for each object type - [`/data/works/manifest`](https://openalex.s3.amazonaws.com/data/works/manifest) lists all the works. * The gzip-compressed snapshot takes up about 330 GB and decompresses to about 1.6 TB. The structure of each entity type is documented here: [Work](https://docs.openalex.org/api-entities/works/work-object) , [Author](https://docs.openalex.org/api-entities/authors/author-object) , [Source](https://docs.openalex.org/api-entities/sources/source-object) , [Institution](https://docs.openalex.org/api-entities/institutions/institution-object) , [Concept](https://docs.openalex.org/api-entities/concepts/concept-object) , and [Publisher](https://docs.openalex.org/api-entities/publishers/publisher-object) . We have recently added folders for new entities `topics`, `fields`, `subfields`, and `domains`, and we will be adding others soon. This documentation will soon be updated to reflect these changes. #### [](https://docs.openalex.org/download-all-data/snapshot-data-format#visualization-of-the-entity_type-updated_date-folder-structure) Visualization of the entity\_type/updated\_date folder structure This is a screenshot showing the "leaf" nodes of one _entity type_, _updated date_ folder. You can also click around the browser links above to get a sense of the snapshot's structure. ### [](https://docs.openalex.org/download-all-data/snapshot-data-format#downloading-updated-entities) Downloading updated Entities Once you have a copy of the snapshot, you'll probably want to keep it up to date. The `updated_date` partitions make this easy, but the way they work may be unfamiliar. Unlike a set of dated snapshots that each contain the full dataset as of a certain date, each partition contains the records that last changed on that date. If we imagine launching OpenAlex on 2021-12-30 with 1000 `Authors`, each being newly created on that date, `/data/authors/` looks like this: If, on 2022-01-04, we made changes to 50 of those `Authors`, they would come _out of_ one of the files in `/data/authors/updated_date=2021-12-30` and go _into_ one in `/data/authors/updated_date=2022-01-04:` If we also discovered 50 _new_ Authors, they would go in that same partition, so the totals would look like this: So if you made your copy of the snapshot on 2021-12-30, you would only need to download `/data/authors/updated_date=2022-01-04` to get everything that was changed or added since then. To update a snapshot copy that you created or updated on date `X`, insert or update the records in objects where `updated_date` > `X`_._ You never need to go back for a partition you've already downloaded. Anything that changed isn't there anymore, it's in a new partition. At the time of writing, these are the `Author` partitions and the number of records in each (in the actual dataset): * `updated_date=2021-12-30/` - 62,573,099 * `updated_date=2022-12-31/` - 97,559,192 * `updated_date=2022-01-01/` - 46,766,699 * `updated_date=2022-01-02/` - 1,352,773 This reflects the creation of the dataset on 2021-12-30 and 145,678,664 combined updates and inserts since then - 1,352,773 of which were on 2022-01-02. Over time, the number of partitions will grow. If we make a change that affects all records, the partitions before the date of the change will disappear. ### [](https://docs.openalex.org/download-all-data/snapshot-data-format#merged-entities) Merged Entities See [Merged Entities](https://docs.openalex.org/how-to-use-the-api/get-single-entities#merged-entity-ids) for an explanation of what Entity merging is and why we do it. Alongside the folders for the six Entity types - work, author, source, institution, concept, and publisher - you'll find a seventh folder: [merged\_ids](https://openalex.s3.amazonaws.com/browse.html#data/merged_ids/) . Within this folder you'll find the IDs of Entities that have been merged away, along with the Entity IDs they were merged into. Keep in mind that merging an Entity ID is a way of deleting the Entity while persisting its ID in OpenAlex. In practice, you can just delete the Entity it belongs to. It's not necessary to keep track of the date or which entity it was merged into. Merge operations are separated into files by date. Each file lists the IDs of Entities that were merged on that date, and names the Entities they were merged into. For example, `data/merged_ids/authors/2022-06-07.csv.gz` begins: When processing this file, all you need to do is delete A2257618939. The effects of merging these authors, like crediting A2208157607 with their Works, are already reflected in the affected Entities. Like the Entities' _updated\_date_ partitions, you only ever need to download merged\_ids files that are new to you. Any later merges will appear in new files with later dates. ### [](https://docs.openalex.org/download-all-data/snapshot-data-format#the-manifest-file) The `manifest` file When we start writing a new `updated_date` partition for an entity, we'll delete that entity's `manifest` file. When we finish writing the partition, we'll recreate the manifest, including the newly-created objects. So if `manifest` is there, all the entities are there too. The file is in [redshift manifest](https://docs.aws.amazon.com/redshift/latest/dg/loading-data-files-using-manifest.html) format. To use it as part of the update process for an Entity type (we'll keep using Authors as an example): 1. Download [`s3://openalex/data/authors/manifest`](https://openalex.s3.amazonaws.com/data/authors/manifest) `.` 2. Get the file list from the `url` property of each item in the `entries` list. 3. Download any objects with an `updated_date` you haven't seen before. 4. Download [`s3://openalex/data/authors/manifest`](https://openalex.s3.amazonaws.com/data/authors/manifest) again. If it hasn't changed since (1), no records moved around and any date partitions you downloaded are valid. 5. Decompress the files you downloaded and parse one JSON `Author` per line. Insert or update into your database of choice, using [each entity's ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) as a primary key. If you’ve worked with dataset like this before and have a toolchain picked out, this may be all you need to know. If you want more detailed steps, proceed to [download the data](https://docs.openalex.org/download-all-data/download-to-your-machine) . [PreviousOpenAlex snapshot](https://docs.openalex.org/download-all-data/openalex-snapshot) [NextDownload to your machine](https://docs.openalex.org/download-all-data/download-to-your-machine) Last updated 22 days ago * [Downloading updated Entities](https://docs.openalex.org/download-all-data/snapshot-data-format#downloading-updated-entities) * [Merged Entities](https://docs.openalex.org/download-all-data/snapshot-data-format#merged-entities) * [The manifest file](https://docs.openalex.org/download-all-data/snapshot-data-format#the-manifest-file) Copy /data/authors/ ├── manifest └── updated_date=2021-12-30 [1000 Authors]    ├── 0000_part_00.gz ...    └── 0031_part_00.gz Copy /data/authors/ ├── manifest ├── updated_date=2021-12-30 [950 Authors] │   ├── 0000_part_00.gz │ ... │   └── 0031_part_00.gz └── updated_date=2022-01-04 [50 Authors] ├── 0000_part_00.gz ... └── 0031_part_00.gz Copy /data/authors/ ├── manifest ├── updated_date=2021-12-30 [950 Authors] │   ├── 0000_part_00.gz │ ... │   └── 0031_part_00.gz └── updated_date=2022-01-04 [100 Authors] ├── 0000_part_00.gz ... └── 0031_part_00.gz Copy /data/merged_ids/ ├── authors │   └── 2022-06-07.csv.gz ├── institutions │   └── 2022-06-01.csv.gz ├── venues │   └── 2022-06-03.csv.gz └── works └── 2022-06-06.csv.gz Copy merge_date,id,merge_into_id 2022-06-07,A2257618939,A2208157607 --- # Get single entities | OpenAlex technical documentation This is a more detailed guide to single entities in OpenAlex. If you're just getting started, check out [get a single work](https://docs.openalex.org/api-entities/works/get-a-single-work) . It's easy to get a singleton entity object from from the API:`//.` Here's an example: * Get the work with the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) `W2741809807`: [`https://api.openalex.org/works/W2741809807`](https://api.openalex.org/works/W2741809807) That will return a [`Work`](https://docs.openalex.org/api-entities/works/work-object) object, describing everything OpenAlex knows about the work with that ID. You can use IDs other than OpenAlex IDs, and you can also format the IDs in different ways. Read below to learn more. You can make up to 50 of these queries at once by [requesting a list of entities and filtering on IDs using OR syntax](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) . To get a single entity, you need a single _unambiguous_ identifier, like an ORCID or an OpenAlex ID. If you've got an ambiguous identifier (like an author's name), you'll want to [search](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) instead. [](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) The OpenAlex ID --------------------------------------------------------------------------------------------------------- The OpenAlex ID is the primary key for all entities. It's a URL shaped like this: `https://openalex.org/`. Here's a real-world example: [`https://openalex.org/W2741809807`](https://openalex.org/W2741809807) ### [](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-key) The OpenAlex Key The OpenAlex ID has two parts. The first part is the Base; it's always `https://openalex.org/.` The second part is the Key; it's the unique primary key that identifies a given resource in our database. The key starts with a letter; that letter tells you what kind of entity you've got: **W**(ork), **A**(uthor), **S**(ource), **I**(nstitution), **C**(oncept), **P**(ublisher), or **F**(under). The IDs are not case-sensitive, so `w2741809807` is just as valid as `W2741809807`. So in the example above, the Key is `W2741809807`, and the `W` at the front tells us that this is a `Work`. Because OpenAlex was launched as a replacement for [Microsoft Academic Graph (MAG)](https://www.microsoft.com/en-us/research/project/microsoft-academic-graph/) , OpenAlex IDs are designed to be backwards-compatible with MAG IDs, where they exist. To find the MAG ID, just take the first letter off the front of the unique part of the ID (so in the example above, the MAG ID is `2741809807`). Of course this won't yield anything useful for entities that don't have a MAG ID. [](https://docs.openalex.org/how-to-use-the-api/get-single-entities#merged-entity-ids) Merged Entity IDs ------------------------------------------------------------------------------------------------------------- At times we need to merge two Entities, effectively deleting one of them. This usually happens when we discover two Entities that represent the same real-world entity - for example, two [`Authors`](https://docs.openalex.org/api-entities/authors) that are really the same person. If you request an Entity using its OpenAlex ID, and that Entity has been merged into another Entity, you will be redirected to the Entity it has been merged into. For example, https://openalex.org/A5092938886 has been merged into https://openalex.org/A5006060960, so in the API the former will redirect to the latter: Most clients will handle this transparently; you'll get the data for author A5006060960 without knowing the redirect even happened. If you have stored Entity ID lists and _do_ notice the redirect, you might as well replace the merged-away ID to skip the redirect next time. [](https://docs.openalex.org/how-to-use-the-api/get-single-entities#supported-ids) Supported IDs ----------------------------------------------------------------------------------------------------- For each entity type, you can retrieve the entity using by any of the external IDs we support--not just the native OpenAlex IDs. So for example: * Get the work with this doi: `https://doi.org/10.7717/peerj.4375`: [https://api.openalex.org/works/https://doi.org/10.7717/peerj.4375](https://api.openalex.org/works/https://doi.org/10.7717/peerj.4375) This works with DOIs, ISSNs, ORCIDs, and lots of other IDs...in fact, you can use any ID listed in an entity's `ids` property, as listed below: * [`Work.ids`](https://docs.openalex.org/api-entities/works/work-object#ids) * [`Author.ids`](https://docs.openalex.org/api-entities/authors/author-object#ids) * [`Source.ids`](https://docs.openalex.org/api-entities/sources/source-object#ids) * [`Institution.ids`](https://docs.openalex.org/api-entities/institutions/institution-object#ids) * [`Concept.ids`](https://docs.openalex.org/api-entities/concepts/concept-object#ids) * [`Publisher.ids`](https://docs.openalex.org/api-entities/publishers/publisher-object#ids) [](https://docs.openalex.org/how-to-use-the-api/get-single-entities#id-formats) ID formats ----------------------------------------------------------------------------------------------- Most of the external IDs OpenAlex supports are canonically expressed as URLs...for example, [the canonical form of a DOI](https://www.crossref.org/display-guidelines/) always starts with `https://doi.org/`. You can always use these URL-style IDs in the entity endpoints. Examples: * Get the institution with the ROR [https://ror.org/02y3ad647](https://ror.org/02y3ad647) (University of Florida): [`https://api.openalex.org/institutions/https://ror.org/02y3ad647`](https://api.openalex.org/institutions/https://ror.org/02y3ad647) * Get the author with the ORCID [https://orcid.org/0000-0003-1613-5981](https://orcid.org/0000-0003-1613-5981) (Heather Piwowar): [`https://api.openalex.org/authors/https://orcid.org/0000-0003-1613-5981`](https://api.openalex.org/authors/https://orcid.org/0000-0003-1613-5981) For simplicity and clarity, you may also want to express those IDs in a simpler, URN-style format, and that's supported as well; you just write the namespace of the ID, followed by the ID itself. Here are the same examples from above, but in the namespace:id format: * Get the institution with the ROR [https://ror.org/02y3ad647](https://ror.org/02y3ad647) (University of Florida): [`https://api.openalex.org/institutions/ror:02y3ad647`](https://api.openalex.org/institutions/ror:02y3ad647) * Get the author with the ORCID [https://orcid.org/0000-0003-1613-5981](https://orcid.org/0000-0003-1613-5981) (Heather Piwowar): [`https://api.openalex.org/authors/orcid:0000-0003-1613-5981`](https://api.openalex.org/authors/orcid:0000-0003-1613-5981) Finally, if you're using an OpenAlex ID, you can be even more succinct, and just use the [Key](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-key) part of the ID all by itself, the part that looks like `w1234567`: * Get the work with OpenAlex ID https://openalex.org/W2741809807: [https://api.openalex.org/works/W2741809807](https://api.openalex.org/works/W2741809807) [](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) Canonical External IDs ----------------------------------------------------------------------------------------------------------------------- Every entity has an OpenAlex ID. Most entities also have IDs in other systems, too. There are hundreds of different ID systems, but we've selected a single external ID system for each entity to provide the **Canonical External ID**\--this is the ID in the system that's been most fully adopted by the community, and is most frequently used in the wild. We support other external IDs as well, but the canonical ones get a privileged spot in the API and dataset. These are the Canonical External IDs: * Works: [DOI](https://docs.openalex.org/api-entities/works/work-object#title) * Authors: [ORCID](https://docs.openalex.org/api-entities/authors/author-object#orcid) * Sources: [ISSN-L](https://docs.openalex.org/api-entities/sources/source-object#issn_l) * Institutions: [ROR ID](https://docs.openalex.org/api-entities/institutions/institution-object#ror) * Concepts: [Wikidata ID](https://docs.openalex.org/api-entities/concepts/concept-object#wikidata) * Publishers: [Wikidata ID](https://docs.openalex.org/api-entities/publishers/publisher-object#ids) [](https://docs.openalex.org/how-to-use-the-api/get-single-entities#dehydrated-entity-objects) Dehydrated entity objects ----------------------------------------------------------------------------------------------------------------------------- The full entity objects can get pretty unwieldy, especially when you're embedding a list of them in another object (for instance, a list of `Concept`s in a `Work`). For these cases, all the entities except `Work`s have a dehydrated version. This is a stripped-down representation of the entity that carries only its most essential properties. These properties are documented individually on their respective entity pages. \\ [Previousxpac](https://docs.openalex.org/how-to-use-the-api/xpac) [NextRandom result](https://docs.openalex.org/how-to-use-the-api/get-single-entities/random-result) Last updated 22 days ago * [The OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) * [The OpenAlex Key](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-key) * [Merged Entity IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#merged-entity-ids) * [Supported IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#supported-ids) * [ID formats](https://docs.openalex.org/how-to-use-the-api/get-single-entities#id-formats) * [Canonical External IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) * [Dehydrated entity objects](https://docs.openalex.org/how-to-use-the-api/get-single-entities#dehydrated-entity-objects) Copy $ curl -i https://api.openalex.org/authors/A5092938886 HTTP/1.1 301 MOVED PERMANENTLY Location: https://api.openalex.org/authors/A5006060960 --- # Filter concepts | OpenAlex technical documentation These are the original OpenAlex Concepts, which are being deprecated in favor of [Topics](https://docs.openalex.org/api-entities/topics) . We will continue to provide these Concepts for Works, but we will not be actively maintaining, updating, or providing support for these concepts. Unless you have a good reason to be relying on them, we encourage you to look into [Topics](https://docs.openalex.org/api-entities/topics) instead. You can filter concepts with the `filter` parameter: * Get concepts that are at level 0 (top level) [`https://api.openalex.org/concepts?filter=level:0`](https://api.openalex.org/concepts?filter=level:0) It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query ### [](https://docs.openalex.org/api-entities/concepts/filter-concepts#concepts-attribute-filters) `/concepts` attribute filters You can filter using these attributes of the [`Concept`](https://docs.openalex.org/api-entities/concepts/concept-object) object (click each one to view their documentation on the `Concept` object page): * [`ancestors.id`](https://docs.openalex.org/api-entities/concepts/concept-object#ancestors) * [`cited_by_count`](https://docs.openalex.org/api-entities/concepts/concept-object#cited_by_count) * [`ids.openalex`](https://docs.openalex.org/api-entities/concepts/concept-object#ids) (alias: `openalex`) * [`level`](https://docs.openalex.org/api-entities/concepts/concept-object#level) * [`summary_stats.2yr_mean_citedness`](https://docs.openalex.org/api-entities/concepts/concept-object#summary_stats) (accepts float, null, !null, can use range queries such as < >) * [`summary_stats.h_index`](https://docs.openalex.org/api-entities/concepts/concept-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`summary_stats.i10_index`](https://docs.openalex.org/api-entities/concepts/concept-object#summary_stats) (accepts integer, null, !null, can use range queries) * [`works_count`](https://docs.openalex.org/api-entities/concepts/concept-object#works_count) ### [](https://docs.openalex.org/api-entities/concepts/filter-concepts#concepts-convenience-filters) `/concepts` convenience filters These filters aren't attributes of the [`Concept`](https://docs.openalex.org/api-entities/concepts/concept-object) object, but they're included to address some common use cases: #### [](https://docs.openalex.org/api-entities/concepts/filter-concepts#default.search) `default.search` Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/concepts/search-concepts#search-concepts) for Concepts. #### [](https://docs.openalex.org/api-entities/concepts/filter-concepts#display_name.search) `display_name.search` Value: a search string Returns: concepts with a [`display_name`](https://docs.openalex.org/api-entities/concepts/concept-object#display_name) containing the given string; see the [search page](https://docs.openalex.org/api-entities/concepts/search-concepts#search-a-specific-field) for details. * Get concepts with `display_name` containing "electrodynamics": [`https://api.openalex.org/concepts?filter=display_name.search:electrodynamics`](https://api.openalex.org/concepts?filter=display_name.search:electrodynamics) In most cases, you should use the [`search` parameter](https://docs.openalex.org/api-entities/concepts/search-concepts#concepts-full-search) instead of this filter because it uses a better search algorithm. #### [](https://docs.openalex.org/api-entities/concepts/filter-concepts#has_wikidata) `has_wikidata` Value: a Boolean (`true` or `false`) Returns: concepts that have or lack a [Wikidata ID](https://docs.openalex.org/api-entities/concepts/concept-object#wikidata) , depending on the given value. For now, all concepts in OpenAlex _do_ have Wikidata IDs. * Get concepts without Wikidata IDs: [`https://api.openalex.org/concepts?filter=has_wikidata:false`](https://api.openalex.org/concepts?filter=has_wikidata:false) [PreviousGet lists of concepts](https://docs.openalex.org/api-entities/concepts/get-lists-of-concepts) [NextSearch concepts](https://docs.openalex.org/api-entities/concepts/search-concepts) Last updated 21 days ago * [/concepts attribute filters](https://docs.openalex.org/api-entities/concepts/filter-concepts#concepts-attribute-filters) * [/concepts convenience filters](https://docs.openalex.org/api-entities/concepts/filter-concepts#concepts-convenience-filters) --- # Load to a relational database | OpenAlex technical documentation Compared to using a data warehouse, loading the dataset into a relational database takes more work up front but lets you write simpler queries and run them on less powerful machines. One important caveat is that this is a _lot_ of data, and exploration will be very slow in most relational databases. By using a relational database, you trade flexibility for efficiency in certain selected operations. The tables, columns, and indexes we have chosen in this guide represent only one of many ways the entity objects could be stored. It may not be the best way to store them given the queries you want to run. Some queries will be fast, others will be painfully slow. We’re going to use [PostgreSQL](https://www.postgresql.org/) as an example and skip the database server setup itself. We’ll assume you have a working postgres 13+ installation on which you can create schemas and tables and run queries. With that as a starting point, we'll take you through these steps: 1. Define the tables the data will be stored in and some key relationships between them (the "schema"). 2. Convert the [JSON Lines](https://jsonlines.org/) files you [downloaded](https://docs.openalex.org/download-all-data/download-to-your-machine) to [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) files that can be read by the database application. We'll flatten them to fit a [hierarchical database model](https://en.wikipedia.org/wiki/Hierarchical_database_model) . 3. Load the CSV data into to the tables you created. 4. Run some queries on the data you loaded. [](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database#step-1-create-the-schema) Step 1: Create the schema ------------------------------------------------------------------------------------------------------------------------------------------------------------- Running [this SQL](https://github.com/ourresearch/openalex-documentation-scripts/blob/main/openalex-pg-schema.sql) on your database (in the [psql](https://www.postgresql.org/docs/13/app-psql.html) client, for example) will initialize a schema for you. Run it and you'll be set up to follow the next steps. To show you what it's doing, we'll explain some excerpts here, using the [concept](https://docs.openalex.org/api-entities/concepts) entity as an example. SQL in this section isn't anything additional you need to run. It's part of the schema we already defined in the file above. The key thing we're doing is "flattening" the nested JSON data. Some parts of this are easy. [Concept.id](https://docs.openalex.org/api-entities/concepts/concept-object#id) is just a string, so it goes in a text column called "id": Copy CREATE TABLE openalex.concepts ( id text NOT NULL, -- plus some other columns ... ); But [Concept.related\_concepts](https://docs.openalex.org/api-entities/concepts/concept-object#related_concepts) isn't so simple. You could store the JSON array intact in a postgres [JSON or JSONB](https://www.postgresql.org/docs/9.4/datatype-json.html) column, but you would lose much of the benefit of a relational database. It would be hard to answer questions about related concepts with more than one degree of separation, for example. So we make a separate table to hold these relationships: We can preserve `score` in this relationship table and look up any other attributes of the [dehydrated related concepts](https://docs.openalex.org/api-entities/concepts/concept-object#the-dehydratedconcept-object) in the main table `concepts`. Creating indexes on `concept_id` and `related_concept_id` lets us look up concepts on both sides of the relationship quickly. [](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database#step-2-convert-the-json-lines-files-to-csv) Step 2: Convert the JSON Lines files to CSV ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [This python script](https://github.com/ourresearch/openalex-documentation-scripts/blob/main/flatten-openalex-jsonl.py) will turn the JSON Lines files you downloaded into CSV files that can be copied to the the tables you created in step 1. This script assumes your downloaded snapshot is in `openalex-snapshot` and you've made a directory `csv-files` to hold the CSV files. Edit `SNAPSHOT_DIR` and `CSV_DIR` at the top of the script to read or write the files somewhere else. This script has only been tested using python 3.9.5. Copy the script to the directory above your snapshot (if the snapshot is in `/home/yourname/openalex/openalex-snapshot/`, name it something like `/home/yourname/openalex/flatten-openalex-jsonl.py)` run it like this: This script is slow. Exactly how slow depends on the machine you run it on, but think hours, not minutes. If you're familiar with python, there are two big improvements you can make: * Run [`flatten_authors`](https://github.com/ourresearch/openalex-documentation-scripts/blob/main/flatten-openalex-jsonl.py#L214) and [`flatten_works`](https://github.com/ourresearch/openalex-documentation-scripts/blob/main/flatten-openalex-jsonl.py#L544) at the same time, either by using threading in python or just running two copies of the script with the appropriate lines commented out. * Flatten multiple `.gz` files within each entity type at the same time. This means parallelizing the `for jsonl_file_name ... loop` in each `flatten_` function and writing multiple CSV files per entity type. You should now have a directory full of nice, flat CSV files: [](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database#step-3-load-the-csv-files-to-the-database) Step 3: Load the CSV files to the database ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Now we run one postgres copy command to load each CSV file to its corresponding table. Each command looks like this: [This script](https://github.com/ourresearch/openalex-documentation-scripts/blob/main/copy-openalex-csv.sql) will run all the copy commands in the right order. Here's how to run it: 1. Copy it to the same place as the python script from step 2, right above the folder with your CSV files. 2. Set the environment variable OPENALEX\_SNAPSHOT\_DB to the [connection URI](https://www.postgresql.org/docs/13/libpq-connect.html#LIBPQ-CONNSTRING) for your database. 3. If your CSV files aren't in `csv-files`, replace each occurence of 'csv-files/' in the script with the correct path. 4. Run it like this (from your shell prompt) or like this (from psql) There are a bunch of ways you can do this - just run the copy commands from the script above in the right order in whatever client you're familiar with. [](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database#step-4-run-your-queries) Step 4: Run your queries! ------------------------------------------------------------------------------------------------------------------------------------------------------------ Now you have all the OpenAlex data in your database and can run queries in your favorite client. Here’s a simple one, getting the OpenAlex ID and OA status for each work: You'll get results like this (truncated, the actual result will be millions of rows): id oa\_status [https://openalex.org/W1496190310](https://openalex.org/W1496190310) closed [https://openalex.org/W2741809807](https://openalex.org/W2741809807) gold [https://openalex.org/W1496404095](https://openalex.org/W1496404095) bronze Here’s an example of a more complex query - finding the author with the most open access works of all time: We get the one row we asked for: author\_id num\_oa\_works https://openalex.org/A2798520857 3297 Checking out [https://api.openalex.org/authors/A2798520857](https://api.openalex.org/authors/A2798520857) , we see that this is Ashok Kumar at Manipal University Jaipur. We could also have found this directly in the query, through `openalex.authors`. [PreviousLoad to a data warehouse](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse) [NextPostgres schema diagram](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database/postgres-schema-diagram) Last updated 22 days ago * [Step 1: Create the schema](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database#step-1-create-the-schema) * [Step 2: Convert the JSON Lines files to CSV](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database#step-2-convert-the-json-lines-files-to-csv) * [Step 3: Load the CSV files to the database](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database#step-3-load-the-csv-files-to-the-database) * [Step 4: Run your queries!](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database#step-4-run-your-queries) Copy CREATE TABLE openalex.concepts_related_concepts ( concept_id text, related_concept_id text, score real ); Copy mkdir -p csv-files python3 flatten-openalex-jsonl.py Copy $ tree csv-files/ csv-files/ ├── concepts.csv ├── concepts_ancestors.csv ├── concepts_counts_by_year.csv ├── concepts_ids.csv └── concepts_related_concepts.csv ... $ cat csv-files/concepts_related_concepts.csv concept_id,related_concept_id,score https://openalex.org/C41008148,https://openalex.org/C33923547,253.92 https://openalex.org/C41008148,https://openalex.org/C119599485,153.019 https://openalex.org/C41008148,https://openalex.org/C121332964,143.935 ... Copy \copy openalex.concepts_ancestors (concept_id, ancestor_id) from csv-files/concepts_ancestors.csv csv header Copy psql $OPENALEX_SNAPSHOT_DB < copy-openalex-csv.sql Copy \i copy-openalex-csv.sql Copy select w.id, oa.oa_status from openalex.works w join openalex.works_open_access oa on w.id = oa.work_id; Copy select author_id, count(distinct work_id) as num_oa_works from ( select a.id as author_id, w.id as work_id, oa.is_oa from openalex.authors a join openalex.works_authorships wa on a.id = wa.author_id join openalex.works w on wa.work_id = w.id join openalex.works_open_access oa on w.id = oa.work_id ) work_authorships_oa where is_oa group by 1 order by 2 desc limit 1; --- # Get groups of entities | OpenAlex technical documentation Sometimes instead of just listing entities, you want to _group them_ into facets, and count how many entities are in each group. For example, maybe you want to count the number of `Works` by [open access status](https://docs.openalex.org/api-entities/works/work-object#open_access) . To do that, you call the entity endpoint, adding the `group_by` parameter. Example: * Get counts of works by type: [`https://api.openalex.org/works?group_by=type`](https://api.openalex.org/works?group_by=type) This returns a `meta` object with details about the query, and a `group_by` object with the groups you've asked for: Copy { meta: { count: 246136992, db_response_time_ms: 271, page: 1, per_page: 200, groups_count: 15 }, group_by: [\ {\ key: "article",\ key_display_name: "article",\ count: 202814957\ },\ {\ key: "book-chapter",\ key_display_name: "book-chapter",\ count: 21250659\ },\ {\ key: "dissertation",\ key_display_name: "dissertation",\ count: 6055973\ },\ {\ key: "book",\ key_display_name: "book",\ count: 5400871\ },\ ...\ ] } So from this we can see that the majority of works (202,814,957 of them) are type `article`, with another 21,250,659 `book-chapter`, and so forth. You can group by most of the same properties that you can [filter](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) by, and you can combine grouping with filtering. [](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#group-properties) Group properties -------------------------------------------------------------------------------------------------------------- Each group object in the `group_by` list contains three properties: #### [](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#key) `key` Value: a string; the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) or raw value of the `group_by` parameter for members of this group. See details on [`key` and `key_display_name`](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#key-and-key_display_name) . #### [](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#key_display_name) `key_display_name` Value: a string; the `display_name` or raw value of the `group_by` parameter for members of this group. See details on [`key` and `key_display_name`](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#key-and-key_display_name) . #### [](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#count) `count` Value: an integer; the number of entities in the group. [](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#unknown-groups) "Unknown" groups ------------------------------------------------------------------------------------------------------------ The "unknown" group is hidden by default. If you want to include this group in the response, add `:include_unknown` after the group-by parameter. * Group works by [`authorships.countries`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#countries) (unknown group hidden): [`https://api.openalex.org/works?group_by=authorships.countries`](https://api.openalex.org/works?group_by=authorships.countries) * Group works by [`authorships.countries`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#countries) (includes unknown group): [`https://api.openalex.org/works?group_by=authorships.countries:include_unknown`](https://api.openalex.org/works?group_by=authorships.countries:include_unknown) [](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#key-and-key_display_name) `key` and `key_display_name` ---------------------------------------------------------------------------------------------------------------------------------- If the value being grouped by is an OpenAlex `Entity`, the [`key`](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#key) and [`key_display_name`](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#key_display_name) properties will be that `Entity`'s `id` and `display_name`, respectively. * Group `Works` by `Institution`: [`https://api.openalex.org/works?group_by=authorships.institutions.id`](https://api.openalex.org/works?group_by=authorships.institutions.id) * For one group, `key` is "[https://openalex.org/I136199984](https://openalex.org/I136199984) " and `key_display_name` is "Harvard University". Otherwise, `key` is the same as `key_display_name`; both are the raw value of the `group_by` parameter for this group. * Group `Concepts` by [`level`](https://docs.openalex.org/api-entities/concepts/concept-object#level) : [`https://api.openalex.org/concepts?group_by=level`](https://api.openalex.org/concepts?group_by=level) * For one group, both `key` and `key_display_name` are "3". [](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#group-by-meta-properties) Group-by `meta` properties -------------------------------------------------------------------------------------------------------------------------------- `meta.count` is the total number of works (this will be all works if no filter is applied). `meta.groups_count` is the count of groups (in the current page). If there are no groups in the response, `meta.groups_count` is `null`. Due to a technical limitation, we can only report the number of groups _in the current page,_ and not the total number of groups. [](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#paging) Paging ------------------------------------------------------------------------------------------ The maximum number of groups returned is 200. If you want to get more than 200 groups, you can use cursor pagination. This works the same as it does when getting lists of entities, so [head over to the section on paging through lists of results](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#cursor-paging) to learn how. Due to technical constraints, when paging, results are sorted by key, rather than by count. [PreviousAutocomplete entities](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities) [NextRate limits and authentication](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication) Last updated 22 days ago * [Group properties](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#group-properties) * ["Unknown" groups](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#unknown-groups) * [key and key\_display\_name](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#key-and-key_display_name) * [Group-by meta properties](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#group-by-meta-properties) * [Paging](https://docs.openalex.org/how-to-use-the-api/get-groups-of-entities#paging) --- # Load to a data warehouse | OpenAlex technical documentation In many data warehouse and document store applications, you can load the OpenAlex entities as-is and query them directly. We’ll use [BigQuery](https://cloud.google.com/bigquery) as an example here. ([Elasticsearch](https://www.elastic.co/elasticsearch/) docs coming soon). To follow along you’ll need the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install) . You’ll also need a Google account that can make BigQuery tables that are, well… big. Which means it probably won’t be free. We'll show you how to do this in 4 steps: 1. Create a BigQuery Project and Dataset to hold your tables 2. Create the tables that will hold your entity JSON records 3. Copy the data files to the tables you created 4. Run some queries on the data you loaded Several users have contributed more self-contained scripts for this. We haven't tested these but they may be easier options: \* [https://github.com/naustica/openalex](https://github.com/naustica/openalex) \* [https://github.com/DrorSh/openalex\_to\_gbq](https://github.com/DrorSh/openalex_to_gbq) [Snowflake](https://www.snowflake.com/) users can connect to a ready-to-query data set on the marketplace, helpfully maintained by [Util](https://www.util.co/) - [https://app.snowflake.com/marketplace/listing/GZT0ZOMX4O7](https://app.snowflake.com/marketplace/listing/GZT0ZOMX4O7) [](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse#step-1-create-a-bigquery-project-and-dataset) **Step 1: Create a BigQuery Project and Dataset** ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In BigQuery, you need a [Project](https://cloud.google.com/resource-manager/docs/creating-managing-projects) and [Dataset](https://cloud.google.com/bigquery/docs/datasets-intro) to hold your tables. We’ll call the project “openalex-demo” and the dataset “openalex”. Follow the linked instructions to create the Project, then create the dataset inside it: Copy bq mk openalex-demo:openalex > `Dataset 'openalex-demo:openalex' successfully created` [](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse#step-2-create-tables-for-each-entity-type) Step 2: Create tables for each entity type ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Now, we’ll [create tables](https://cloud.google.com/bigquery/docs/tables) inside the dataset. There will be 5 tables, one for each entity type. Since we’re using JSON, each table will have just one text column named after the table. Copy bq mk --table openalex-demo:openalex.works work:string > `Table 'openalex-demo:openalex.works' successfully created.` > `Table 'openalex-demo:openalex.authors' successfully created` and so on for `sources`, `institutions`, `concepts,` and `publishers`. [](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse#step-3-load-the-data-files) Step 3: Load the data files ------------------------------------------------------------------------------------------------------------------------------------------------------------ We’ll load each table’s data from the JSON Lines files we downloaded earlier. For `works`, the files were: * openalex-snapshot/data/works/updated\_date=2021-12-28/0000\_part\_00.gz * openalex-snapshot/data/works/updated\_date=2021-12-28/0001\_part\_00.gz Here’s a command to load one `works` file (don’t run it yet): See the full documentation for the `bq load` command here: [https://cloud.google.com/bigquery/docs/reference/bq-cli-reference#bq\_load](https://cloud.google.com/bigquery/docs/reference/bq-cli-reference#bq_load) This part of the command may need some explanation: > `--source_format=CSV -F '\t' --schema 'work:string'` Bigquery is expecting multiple columns with predefined datatypes (a “schema”). We’re tricking it into accepting a single text column (`--schema 'work:string'`) by specifying [CSV](https://en.wikipedia.org/wiki/Comma-separated_values) format (`--source_format=CSV`) with a column delimiter that isn’t present in the file (`-F '\t')` (\\t means “tab”). `bq load` can only handle one file at a time, so you must run this command once per file. But remember that the real dataset will have many more files than this example does, so it's impractical to copy, edit, and rerun the command each time. It's easier to handle all the files in a loop, like this: This step is slow. _How_ slow depends on your upload speed, but for `Author` and `Work` we're talking hours, not minutes. You can speed this up by using [`parallel`](https://www.gnu.org/software/parallel/) or other tools to run multiple upload commands at once. If you do, watch out for errors caused by hitting [BigQuery quota](https://cloud.google.com/bigquery/docs/troubleshoot-quotas) limits. Do this once per entity type, substituting each entity name for `work`/`works` as needed. When you’re finished, you’ll have five tables that look like this: [](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse#step-4-run-your-queries) **Step 4: Run your queries!** ----------------------------------------------------------------------------------------------------------------------------------------------------------- Now you have the all the OpenAlex data in a place where you can do anything you want with it using [BigQuery JSON functions](https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions) through [bq query](https://cloud.google.com/bigquery/docs/reference/bq-cli-reference#bq_query) or the BigQuery [console](https://console.cloud.google.com/bigquery) . Here’s a simple one, extracting the OpenAlex ID and OA status for each work: It will give you a list of IDs (this is a truncated sample, the real result will be millions of rows): [https://openalex.org/W2741809807](https://openalex.org/W2741809807) TRUE [https://openalex.org/W1491283979](https://openalex.org/W1491283979) FALSE [https://openalex.org/W1491315632](https://openalex.org/W1491315632) FALSE You can run queries like this directly in your shell: But even simple queries are hard to read and edit this way. It’s better to write them in a file than directly on the command line. Here’s an example of a slightly more complex query - finding the author with the most open access works of all time: We get one result: author\_id num\_oa\_works https://openalex.org/A2798520857 3297 Checking out [https://api.openalex.org/authors/A2798520857](https://api.openalex.org/authors/A2798520857) , we see that this is Ashok Kumar at Manipal University Jaipur. [PreviousUpload to your database](https://docs.openalex.org/download-all-data/upload-to-your-database) [NextLoad to a relational database](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-relational-database) Last updated 21 days ago * [Step 1: Create a BigQuery Project and Dataset](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse#step-1-create-a-bigquery-project-and-dataset) * [Step 2: Create tables for each entity type](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse#step-2-create-tables-for-each-entity-type) * [Step 3: Load the data files](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse#step-3-load-the-data-files) * [Step 4: Run your queries!](https://docs.openalex.org/download-all-data/upload-to-your-database/load-to-a-data-warehouse#step-4-run-your-queries) Copy bq mk --table openalex-demo:openalex.authors author:string Copy bq load \ --project_id openalex-demo \ --source_format=CSV -F '\t' \ --schema 'work:string' \ openalex.works \ 'openalex-snapshot/data/works/updated_date=2021-12-28/0000_part_00.gz' Copy for data_file in openalex-snapshot/data/works/*/*.gz; do bq load --source_format=CSV -F '\t' \ --schema 'work:string' \ --project_id openalex-demo \ openalex.works $data_file; done Copy select json_value(work, '$.id') as work_id, json_value(work, '$.open_access.is_oa') as is_oa from `openalex-demo.openalex.works`; Copy bq query \ --project_id=openalex-demo \ --use_legacy_sql=false \ "select json_value(work, '$.id') as work_id, json_value(work, '$.open_access.is_oa') as is_oa from openalex.works;" Copy with work_authorships_oa as ( select json_value(work, '$.id') as work_id, json_query_array(work, '$.authorships') as authorships, cast(json_value(work, '$.open_access.is_oa') as BOOL) as is_oa from `openalex-demo.openalex.works` ), flat_authorships as ( select work_id, authorship, is_oa from work_authorships_oa, unnest(authorships) as authorship ) select json_value(authorship, '$.author.id') as author_id, count(distinct work_id) as num_oa_works from flat_authorships where is_oa group by author_id order by num_oa_works desc limit 1; --- # Institution object | OpenAlex technical documentation These are the fields in an institution object. When you use the API to get a [single institution](https://docs.openalex.org/api-entities/institutions/get-a-single-institution) or [lists of institutions](https://docs.openalex.org/api-entities/institutions/get-lists-of-institutions) , this is what's returned. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#associated_institutions) `associated_institutions` _List:_ `Institutions` related to this one. Each associated institution is represented as a [dehydrated Institution](https://docs.openalex.org/api-entities/institutions/institution-object#the-dehydratedinstitution-object) object, with one extra property: * `relationship` (_String_): The type of relationship between this institution and the listed institution. Possible values: `parent`, `child`, and `related`. Institution associations and the _relationship_ vocabulary come from [ROR's `relationships`](https://ror.readme.io/docs/ror-data-structure#relationships) . Copy associated_institutions: [\ {\ id: "https://openalex.org/I2802101240",\ ror: "https://ror.org/0483mr804",\ display_name: "Carolinas Medical Center",\ country_code: "US",\ type: "healthcare",\ relationship: "related"\ },\ {\ id: "https://openalex.org/I69048370",\ ror: "https://ror.org/01s91ey96",\ display_name: "Renaissance Computing Institute",\ country_code: "US",\ type: "education",\ relationship: "related"\ },\ \ // and so forth\ ] ### [](https://docs.openalex.org/api-entities/institutions/institution-object#cited_by_count) `cited_by_count` _Integer:_ The total number [`Works`](https://docs.openalex.org/api-entities/works/work-object) that cite a work created by an author affiliated with this institution. Or less formally: the number of citations this institution has collected. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#country_code) `country_code` _String:_ The country where this institution is located, represented as an [ISO two-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) . ### [](https://docs.openalex.org/api-entities/institutions/institution-object#counts_by_year) `counts_by_year` _List:_ [`works_count`](https://docs.openalex.org/api-entities/institutions/institution-object#works_count) and [`cited_by_count`](https://docs.openalex.org/api-entities/institutions/institution-object#cited_by_count) for each of the last ten years, binned by year. To put it another way: each year, you can see how many new works this institution put out, and how many times _any_ work affiliated with this institution got cited. Years with zero citations and zero works have been removed so you will need to add those in if you need them. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#created_date) `created_date` _String:_ The date this `Institution` object was created in the OpenAlex dataset, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#display_name) `display_name` _String:_ The primary name of the institution. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#display_name_acronyms) `display_name_acronyms` _List:_ Acronyms or initialisms that people sometimes use instead of the full [`display_name`](https://docs.openalex.org/api-entities/institutions/institution-object#display_name) . ### [](https://docs.openalex.org/api-entities/institutions/institution-object#display_name_alternatives) `display_name_alternatives` _List:_ Other names people may use for this institution. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#geo) `geo` _Object:_ A bunch of stuff we know about the location of this institution: * `city` (_String_): The city where this institution lives. * `geonames_city_id` (_String_): The city where this institution lives, as a [GeoNames database](http://www.geonames.org/) ID. * `region` (_String_): The sub-national region (state, province) where this institution lives. * `country_code` (_String_): The country where this institution lives, represented as an [ISO two-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) . * `country` (_String_): The country where this institution lives. * `latitude` (_Float_): Does what it says. * `longitude` (_Float_): Does what it says. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#homepage_url) `homepage_url` _String:_ The URL for institution's primary homepage. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#id) `id` _String:_ The [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for this institution. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#ids) `ids` _Object:_ All the external identifiers that we know about for this institution. IDs are expressed as URIs whenever possible. Possible ID types: * `grid` (_String:_ this institution's [GRID](https://www.grid.ac/) [ID](https://en.wikipedia.org/wiki/RAS_syndrome) ) * `mag` (_Integer:_ this institution's [Microsoft Academic Graph](https://www.microsoft.com/en-us/research/project/microsoft-academic-graph/) ID) * `openalex` (_String:_ this institution's [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) . Same as [`Institution.id`](https://docs.openalex.org/api-entities/institutions/institution-object#id) ) * `ror` (_String:_ this institution's ROR ID. Same as [`Institution.ror`](https://docs.openalex.org/api-entities/institutions/institution-object#ror) ) * `wikipedia` (_String:_ this institution's Wikipedia page URL) * `wikidata` (_String:_ this institution's [Wikidata ID](https://www.wikidata.org/wiki/Wikidata:Identifiers) ) Many institution are missing one or more ID types (either because we don't know the ID, or because it was never assigned). Keys for null IDs are not displayed. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#image_thumbnail_url) `image_thumbnail_url` _String:_ Same as [`image_url`](https://docs.openalex.org/api-entities/institutions/institution-object#image_url-1) , but it's a smaller image. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#is_super_system) `is_super_system` _Boolean:_ True if this institution is a "super system". This includes large university systems such as the University of California System ([`https://openalex.org/I2803209242`](https://openalex.org/I2803209242) ), as well as some governments and multinational companies. We have this special flag for these institutions so that we can exclude them from other institutions' [`lineage`](https://docs.openalex.org/api-entities/institutions/institution-object#lineage) , which we do because these super systems are not generally relevant in group-by results when you're looking at ranked lists of institutions. The list of institution IDs marked as super systems can be found in [this file](https://github.com/ourresearch/openalex-guts/blob/main/const.py) . ### [](https://docs.openalex.org/api-entities/institutions/institution-object#image_url) `image_url` _String:_ URL where you can get an image representing this institution. Usually this is hosted on Wikipedia, and usually it's a seal or logo. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#international) `international` _Object:_ The institution's display name in different languages. Derived from the wikipedia page for the institution in the given language. * `display_name` (_Object_) * `key` (String): language code in [wikidata language code](https://www.wikidata.org/wiki/Property:P9753) format. Full list of languages is [here](https://doc.wikimedia.org/mediawiki-core/master/php/Names_8php_source.html) . * `value` (String): `display_name` in the given language ### [](https://docs.openalex.org/api-entities/institutions/institution-object#lineage) `lineage` _List:_ [OpenAlex IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) of institutions. The list will include this institution's ID, as well as any parent institutions. If this institution has no parent institutions, this list will only contain its own ID. This information comes from [ROR's `relationships`](https://ror.readme.io/docs/ror-data-structure#relationships) , specifically the Parent/Child relationships. Super systems are excluded from the lineage. See [`is_super_system`](https://docs.openalex.org/api-entities/institutions/institution-object#is_super_system) above. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#repositories) `repositories` _List:_ Repositories ([`Sources`](https://docs.openalex.org/api-entities/sources) with `type: repository`) that have this institution as their [`host_organization`](https://docs.openalex.org/api-entities/sources/source-object#host_organization) ### [](https://docs.openalex.org/api-entities/institutions/institution-object#roles) `roles` _List:_ List of role objects, which include the `role` (one of `institution`, `funder`, or `publisher`), the `id` ([OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) ), and the `works_count`. In many cases, a single organization does not fit neatly into one role. For example, Yale University is a single organization that is a research university, funds research studies, and publishes an academic journal. The `roles` property links the OpenAlex entities together for a single organization, and includes counts for the works associated with each role. The `roles` list of an entity ([Funder](https://docs.openalex.org/api-entities/funders) , [Publisher](https://docs.openalex.org/api-entities/publishers) , or [Institution](https://docs.openalex.org/api-entities/institutions) ) always includes itself. In the case where an organization only has one role, the `roles` will be a list of length one, with itself as the only item. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#ror) `ror` _String:_ The [ROR](https://ror.org/) ID for this institution. This is the [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for institutions. The ROR (Research Organization Registry) identifier is a globally unique ID for research organization. [ROR is the successor to GRiD](https://www.digital-science.com/press-release/grid-passes-torch-to-ror/) , which is no longer being updated. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#summary_stats) `summary_stats` _Object:_ Citation metrics for this institution * `2yr_mean_citedness` _Float_: The 2-year mean citedness for this source. Also known as [impact factor](https://en.wikipedia.org/wiki/Impact_factor) . We use the year prior to the current year for the citations (the numerator) and the two years prior to that for the citation-receiving publications (the denominator). * `h_index` _Integer_: The [_h_\-index](https://en.wikipedia.org/wiki/H-index) for this institution. * `i10_index` _Integer_: The [i-10 index](https://en.wikipedia.org/wiki/Author-level_metrics#i-10-index) for this institution. While the _h_\-index and the i-10 index are normally author-level metrics and the 2-year mean citedness is normally a journal-level metric, they can be calculated for any set of papers, so we include them for institutions. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#type) `type` _String:_ The institution's primary type, using the [ROR "type" controlled vocabulary](https://ror.readme.io/docs/ror-data-structure) . Possible values are: `Education`, `Healthcare`, `Company`, `Archive`, `Nonprofit`, `Government`, `Facility`, and `Other`. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#updated_date) `updated_date` _String:_ The last time anything in this `Institution` changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. This date is updated for _any change at all_, including increases in various counts. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#works_api_url) `works_api_url` _String:_ A URL that will get you a list of all the [`Works`](https://docs.openalex.org/api-entities/works/work-object) affiliated with this institution. We express this as an API URL (instead of just listing the `Works` themselves) because most institutions have way too many works to reasonably fit into a single return object. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#works_count) `works_count` _Integer:_ The number of [`Works`](https://docs.openalex.org/api-entities/works/work-object) created by authors affiliated with this institution. Or less formally: the number of works coming out of this institution. ### [](https://docs.openalex.org/api-entities/institutions/institution-object#x_concepts) `x_concepts` `x_concepts` will be deprecated and removed soon. We will be replacing this functionality with [`Topics`](https://docs.openalex.org/api-entities/topics) instead. _List:_ The [`Concepts`](https://docs.openalex.org/api-entities/concepts/concept-object) most frequently applied to works affiliated with this institution. Each is represented as a [dehydrated Concept](https://docs.openalex.org/api-entities/concepts/concept-object#the-dehydratedconcept-object) object, with one additional attribute: * `score` (_Float_): The strength of association between this institution and the listed concept, from 0-100. [](https://docs.openalex.org/api-entities/institutions/institution-object#the-dehydratedinstitution-object) The `DehydratedInstitution` object --------------------------------------------------------------------------------------------------------------------------------------------------- The `DehydratedInstitution` is a stripped-down [`Institution`](https://docs.openalex.org/api-entities/institutions/institution-object) object, with most of its properties removed to save weight. Its only remaining properties are: * [`country_code`](https://docs.openalex.org/api-entities/institutions/institution-object#country_code) * [`display_name`](https://docs.openalex.org/api-entities/institutions/institution-object#display_name) * [`id`](https://docs.openalex.org/api-entities/institutions/institution-object#id) * [`lineage`](https://docs.openalex.org/api-entities/institutions/institution-object#lineage) * [`ror`](https://docs.openalex.org/api-entities/institutions/institution-object#ror) * [`type`](https://docs.openalex.org/api-entities/institutions/institution-object#type) [PreviousInstitutions](https://docs.openalex.org/api-entities/institutions) [NextGet a single institution](https://docs.openalex.org/api-entities/institutions/get-a-single-institution) Last updated 22 days ago * [associated\_institutions](https://docs.openalex.org/api-entities/institutions/institution-object#associated_institutions) * [cited\_by\_count](https://docs.openalex.org/api-entities/institutions/institution-object#cited_by_count) * [country\_code](https://docs.openalex.org/api-entities/institutions/institution-object#country_code) * [counts\_by\_year](https://docs.openalex.org/api-entities/institutions/institution-object#counts_by_year) * [created\_date](https://docs.openalex.org/api-entities/institutions/institution-object#created_date) * [display\_name](https://docs.openalex.org/api-entities/institutions/institution-object#display_name) * [display\_name\_acronyms](https://docs.openalex.org/api-entities/institutions/institution-object#display_name_acronyms) * [display\_name\_alternatives](https://docs.openalex.org/api-entities/institutions/institution-object#display_name_alternatives) * [geo](https://docs.openalex.org/api-entities/institutions/institution-object#geo) * [homepage\_url](https://docs.openalex.org/api-entities/institutions/institution-object#homepage_url) * [id](https://docs.openalex.org/api-entities/institutions/institution-object#id) * [ids](https://docs.openalex.org/api-entities/institutions/institution-object#ids) * [image\_thumbnail\_url](https://docs.openalex.org/api-entities/institutions/institution-object#image_thumbnail_url) * [is\_super\_system](https://docs.openalex.org/api-entities/institutions/institution-object#is_super_system) * [image\_url](https://docs.openalex.org/api-entities/institutions/institution-object#image_url) * [international](https://docs.openalex.org/api-entities/institutions/institution-object#international) * [lineage](https://docs.openalex.org/api-entities/institutions/institution-object#lineage) * [repositories](https://docs.openalex.org/api-entities/institutions/institution-object#repositories) * [roles](https://docs.openalex.org/api-entities/institutions/institution-object#roles) * [ror](https://docs.openalex.org/api-entities/institutions/institution-object#ror) * [summary\_stats](https://docs.openalex.org/api-entities/institutions/institution-object#summary_stats) * [type](https://docs.openalex.org/api-entities/institutions/institution-object#type) * [updated\_date](https://docs.openalex.org/api-entities/institutions/institution-object#updated_date) * [works\_api\_url](https://docs.openalex.org/api-entities/institutions/institution-object#works_api_url) * [works\_count](https://docs.openalex.org/api-entities/institutions/institution-object#works_count) * [x\_concepts](https://docs.openalex.org/api-entities/institutions/institution-object#x_concepts) * [The DehydratedInstitution object](https://docs.openalex.org/api-entities/institutions/institution-object#the-dehydratedinstitution-object) Copy cited_by_count: 21199844 Copy country_code: "US" Copy counts_by_year: [\ {\ year: 2022,\ works_count: 133,\ cited_by_count: 32731\ },\ {\ year: 2021,\ works_count: 12565,\ cited_by_count: 2180827\ },\ \ // and so forth\ ] Copy created_date: "2017-08-08" Copy display_name: "University of North Carolina at Chapel Hill" Copy display_name_acronyms:["UNC"] Copy display_name_alternatives: [\ "UNC-Chapel Hill"\ ] Copy geo: { city: "Chapel Hill", geonames_city_id: "4460162", region: "North Carolina", country_code: "US", country: "United States", latitude: 35.9083, longitude: -79.0492 } Copy homepage_url: "http://www.unc.edu/" Copy id: "https://openalex.org/I114027177" Copy ids: { openalex: "https://openalex.org/I114027177", ror: "https://ror.org/0130frc33", grid: "grid.10698.36", wikipedia: "https://en.wikipedia.org/wiki/University%20of%20North%20Carolina%20at%20Chapel%20Hill", wikidata: "https://www.wikidata.org/wiki/Q192334", mag: 114027177 }   Copy image_thumbnail_url: "https://upload.wikimedia.org/wikipedia/en/thumb/5/5c/University_of_North_Carolina_at_Chapel_Hill_seal.svg/100px-University_of_North_Carolina_at_Chapel_Hill_seal.svg.png" Copy image_url: "https://upload.wikimedia.org/wikipedia/en/5/5c/University_of_North_Carolina_at_Chapel_Hill_seal.svg" Copy international: { display_name: { "ar": "جامعة نورث كارولينا في تشابل هيل", "en": "University of North Carolina at Chapel Hill", "es": "Universidad de Carolina del Norte en Chapel Hill", "zh-cn": "北卡罗来纳大学教堂山分校", ... } } Copy id: "https://openalex.org/I170203145", ... lineage: [\ "https://openalex.org/I170203145",\ "https://openalex.org/I90344618"\ ] Copy repositories: [\ {\ id: "https://openalex.org/S4306402521",\ display_name: "University of Minnesota Digital Conservancy (University of Minnesota)",\ host_organization: "https://openalex.org/I130238516",\ host_organization_name: "University of Minnesota",\ host_organization_lineage: ["https://openalex.org/I130238516"]\ }\ // and so forth\ ] Copy roles: [\ {\ role: "funder",\ id: "https://openalex.org/F4320308380",\ works_count: 1004,\ },\ {\ role: "publisher",\ id: "https://openalex.org/P4310315589",\ works_count: 13986,\ },\ {\ role: "institution",\ id: "https://openalex.org/I32971472",\ works_count: 250031,\ }\ ] Copy ror: "https://ror.org/0130frc33" Copy summary_stats: { 2yr_mean_citedness: 5.065784263815827, h_index: 985, i10_index: 176682 } Copy type: "education" Copy updated_date: "2022-01-02T00:27:23.088909" Copy works_api_url: "https://api.openalex.org/works?filter=institutions.id:I114027177" Copy works_count: 202704     Copy x_concepts: [\ {\ id: "https://openalex.org/C86803240",\ wikidata: null,\ display_name: "Biology",\ level: 0,\ score: 86.7\ },\ {\ id: "https://openalex.org/C185592680",\ wikidata: null,\ display_name: "Chemistry",\ level: 0,\ score: 51.4\ },\ \ // and so forth\ ] --- # Filter entity lists | OpenAlex technical documentation Filters narrow the list down to just entities that meet a particular condition--specifically, a particular value for a particular attribute. A list of filters are set using the `filter` parameter, formatted like this: `filter=attribute:value,attribute2:value2`. Examples: * Get the works whose [type](https://docs.openalex.org/api-entities/works/work-object#type) is `book`: [`https://api.openalex.org/works?filter=type:book`](https://api.openalex.org/works?filter=type:book) * Get the authors whose name is Einstein: [`https://api.openalex.org/authors?filter=display_name.search:einstein`](https://api.openalex.org/authors?filter=display_name.search:einstein) Filters are case-insensitive. [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#logical-expressions) Logical expressions --------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#inequality) Inequality For numerical filters, use the less-than (`<`) and greater-than (`>`) symbols to filter by inequalities. Example: * Get sources that host more than 1000 works: [`https://api.openalex.org/sources?filter=works_count:>1000`](https://api.openalex.org/sources?filter=works_count:%3E1000) Some attributes have special filters that act as syntactic sugar around commonly-expressed inequalities: for example, the `from_publication_date` filter on `works`. See the endpoint-specific documentation below for more information. Example: * Get all works published between 2022-01-01 and 2022-01-26 (inclusive): [`https://api.openalex.org/works?filter=from_publication_date:2022-01-01,to_publication_date:2022-01-26`](https://api.openalex.org/works?filter=from_publication_date:2022-01-01,to_publication_date:2022-01-26) ### [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#negation-not) Negation (NOT) You can negate any filter, numerical or otherwise, by prepending the exclamation mark symbol (`!`) to the filter value. Example: * Get all institutions _except_ for ones located in the US: [`https://api.openalex.org/institutions?filter=country_code:!us`](https://api.openalex.org/institutions?filter=country_code:!us) ### [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#intersection-and) Intersection (AND) By default, the returned result set includes only records that satisfy _all_ the supplied filters. In other words, filters are combined as an AND query. Example: * Get all works that have been cited more than once _and_ are free to read: [`https://api.openalex.org/works?filter=cited_by_count:>1,is_oa:true`](https://api.openalex.org/works?filter=cited_by_count:%3E1,is_oa:true) To create an AND query within a single attribute, you can either repeat a filter, or use the plus symbol (`+`): * Get all the works that have an author from France _and_ an author from the UK: * Using repeating filters: [`https://api.openalex.org/works?filter=institutions.country_code:fr,institutions.country_code:gb`](https://api.openalex.org/works?filter=institutions.country_code:fr,institutions.country_code:gb) * Using the plus symbol (`+`): [`https://api.openalex.org/works?filter=institutions.country_code:fr+gb`](https://api.openalex.org/works?filter=institutions.country_code:fr+gb) Note that the plus symbol (`+`) syntax will not work for search filters, boolean filters, or numeric filters. ### [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) Addition (OR) Use the pipe symbol (`|`) to input lists of values such that _any_ of the values can be satisfied--in other words, when you separate filter values with a pipe, they'll be combined as an `OR` query. Example: * Get all the works that have an author from France or an author from the UK: [`https://api.openalex.org/works?filter=institutions.country_code:fr|gb`](https://api.openalex.org/works?filter=institutions.country_code:fr|gb) This is particularly useful when you want to retrieve a many records by ID all at once. Instead of making a whole bunch of singleton calls in a loop, you can make one call, like this: * Get the works with DOI `10.1371/journal.pone.0266781` _or_ with DOI `10.1371/journal.pone.0267149` (note the pipe separator between the two DOIs): [`https://api.openalex.org/works?filter=doi:https://doi.org/10.1371/journal.pone.0266781|https://doi.org/10.1371/journal.pone.0267149`](https://api.openalex.org/works?filter=doi:https://doi.org/10.1371/journal.pone.0266781|https://doi.org/10.1371/journal.pone.0267149) You can combine up to 100 values for a given filter in this way. You will also need to use the parameter `per-page=100` to get all of the results per query. See our [blog post](https://blog.ourresearch.org/fetch-multiple-dois-in-one-openalex-api-request/) for a tutorial. You can use OR for values _within_ a given filter, but not _between_ different filters. So this, for example, **doesn't work and will return an error**: * Get either French works _or_ ones published in the journal with ISSN 0957-1558: [`https://api.openalex.org/works?filter=institutions.country_code:fr|primary_location.source.issn:0957-1558`](https://api.openalex.org/works?filter=institutions.country_code:fr|primary_location.source.issn:0957-1558) [](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#available-filters) Available Filters ----------------------------------------------------------------------------------------------------------------------------------- The filters for each entity can be found here: * [Works](https://docs.openalex.org/api-entities/works/filter-works) * [Authors](https://docs.openalex.org/api-entities/authors/filter-authors) * [Sources](https://docs.openalex.org/api-entities/sources/filter-sources) * [Institutions](https://docs.openalex.org/api-entities/institutions/filter-institutions) * [Concepts](https://docs.openalex.org/api-entities/concepts/filter-concepts) * [Publishers](https://docs.openalex.org/api-entities/publishers/filter-publishers) * [Funders](https://docs.openalex.org/api-entities/funders/filter-funders) [PreviousPaging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging) [NextSearch entities](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) Last updated 22 days ago * [Logical expressions](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#logical-expressions) * [Inequality](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#inequality) * [Negation (NOT)](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#negation-not) * [Intersection (AND)](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#intersection-and) * [Addition (OR)](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#addition-or) * [Available Filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#available-filters) --- # Work object | OpenAlex technical documentation There's a lot of useful data inside a work. When you use the API to get a [single work](https://docs.openalex.org/api-entities/works/get-a-single-work) or [lists of works](https://docs.openalex.org/api-entities/works/get-lists-of-works) , this is what's returned. ### [](https://docs.openalex.org/api-entities/works/work-object#abstract_inverted_index) `abstract_inverted_index` _Object:_ The abstract of the work, as an [inverted index](https://en.wikipedia.org/wiki/Inverted_index) , which encodes information about the abstract's words and their positions within the text. [Like Microsoft Academic Graph](https://web.archive.org/web/20220721160540/https://docs.microsoft.com/en-us/academic-services/graph/resources-faq#what-format-are-paper-abstracts-published-in) , OpenAlex doesn't include plaintext abstracts due to legal constraints. Copy abstract_inverted_index: { Despite: [\ 0\ ], growing: [\ 1\ ], interest: [\ 2\ ], in: [\ 3,\ 57,\ 73,\ 110,\ 122\ ], Open: [\ 4,\ 201\ ], Access: [\ 5\ ], ... } #### [](https://docs.openalex.org/api-entities/works/work-object#abstract-inverted-index-coverage) Abstract inverted index coverage Newer works are more likely to have an abstract inverted index. For example, over 60% of works in 2022 have abstract data, compared to 45% for works older than 2000. Full chart is below: ### [](https://docs.openalex.org/api-entities/works/work-object#alternate_host_venues-deprecated) `alternate_host_venues` (deprecated) The `host_venue` and `alternate_host_venues` properties have been deprecated in favor of [`primary_location`](https://docs.openalex.org/api-entities/works/work-object#primary_location) and [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) . The attributes `host_venue` and `alternate_host_venues` are no longer available in the Work object, and trying to access them in filters or group-bys will return an error. ### [](https://docs.openalex.org/api-entities/works/work-object#awards) `awards` _List:_ List of dehydrated [`Award`](https://docs.openalex.org/api-entities/awards/award-object) objects representing awards or grants associated with this work. This replaces the older `grants` property, which has been removed. The new `awards` and [`funders`](https://docs.openalex.org/api-entities/works/work-object#funders) properties provide much more comprehensive funding data. ### [](https://docs.openalex.org/api-entities/works/work-object#authorships) `authorships` _List:_ List of [`Authorship`](https://docs.openalex.org/api-entities/works/work-object/authorship-object) objects, each representing an author and their institution. [Limited to](https://docs.openalex.org/api-entities/authors/limitations) the first 100 authors to maintain API performance. For more information, see the [Authorship object](https://docs.openalex.org/api-entities/works/work-object/authorship-object) page. ### [](https://docs.openalex.org/api-entities/works/work-object#apc_list) `apc_list` _Object:_ Information about this work's APC ([article processing charge](https://en.wikipedia.org/wiki/Article_processing_charge) ). The object contains: * `value`: _Integer_ * `currency`: _String_ * `provenance`: _String_ — the source of this data. Currently the only value is “doaj” (DOAJ) * `value_usd`: _Integer_ — the APC converted into USD This value is the APC list price–the price as listed by the journal’s publisher. That’s not always the price _actually_ paid, because publishers may offer various discounts to authors. Unfortunately we don’t always know this discounted price, but when we do you can find it in [`apc_paid`](https://docs.openalex.org/api-entities/works/work-object#apc_paid) . Currently our only source for this data is [DOAJ](https://doaj.org/) , and so `doaj` is the only value for `apc_list.provenance`, but we’ll add other sources over time. You can use this attribute to find works published in [Diamond open access](https://en.wikipedia.org/wiki/Diamond_open_access) journals by looking at works where `apc_list.value` is zero. See [`open_access.oa_status`](https://docs.openalex.org/api-entities/works/work-object#oa_status) for more info. ### [](https://docs.openalex.org/api-entities/works/work-object#apc_paid) `apc_paid` _Object:_ Estimate of the _paid_ APC ([article processing charge](https://en.wikipedia.org/wiki/Article_processing_charge) ) for this work. The object contains: * `value`: _Integer_ * `currency`: _String_ * `provenance`: _String_ — currently either `openapc` or `doaj`, but more will be added; see below for details. * `value_usd`: _Integer_ — the APC converted into USD You can find the _listed_ APC price (when we know it) for a given work using [`apc_list`](https://docs.openalex.org/api-entities/works/work-object#apc_list) . However, authors don’t always pay the listed price; often they get a discounted price from publishers. This property is our best estimate of the APC actually paid. Our best source for this is the excellent [OpenAPC](https://openapc.net/) project. So, when we have it, we use that data. In this case, `apc_paid.provenance` is set to `openapc`. However, unfortunately OpenAPC data is often unavailable, and so then our best estimate of the paid price is simply the list price. In this case `apc_paid.provenance` will be set to wherever we got the list price from (usually DOAJ). `apc_paid` is an _**estimate**_ using the best available data; often this is simply the journal list price. To use only article-level data, filter using: `apc_paid.provenance == "openapc"`. ### [](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) `best_oa_location` _Object:_ A [`Location`](https://docs.openalex.org/api-entities/works/work-object/location-object) object with the best available open access location for this work. We score open locations to determine which is best using these factors: 1. Must have is\_oa: true 2. type\_:\_ "publisher" is better than "repository". 3. version: "publishedVersion" is better than "acceptedVersion", which is better than "submittedVersion". 4. pdf\_url: A location with a direct PDF link is better than one without. 5. repository rankings: Some major repositories like PubMed Central and arXiv are ranked above others. ### [](https://docs.openalex.org/api-entities/works/work-object#biblio) `biblio` _Object:_ Old-timey bibliographic info for this work. This is mostly useful only in citation/reference contexts. These are all strings because sometimes you'll get fun values like "Spring" and "Inside cover." * `volume` (_String_) * `issue` (_String_) * `first_page` (_String_) * `last_page` (_String_) ### [](https://docs.openalex.org/api-entities/works/work-object#citation_normalized_percentile) `citation_normalized_percentile` _Object:_ The percentile of this work's citation count normalized by work type, publication year, and subfield. This field represents the same information as the FWCI expressed as a percentile. Learn more in the reference article: [Field Weighted Citation Impact (FWCI)](https://help.openalex.org/hc/en-us/articles/24735753007895-Field-Weighted-Citation-Impact-FWCI) . ### [](https://docs.openalex.org/api-entities/works/work-object#cited_by_count) `cited_by_count` _Integer:_ The number of citations to this work. These are the times that other works have cited this work: Other works ➞ This work. ### [](https://docs.openalex.org/api-entities/works/work-object#cited_by_percentile_year) `cited_by_percentile_year` _Object:_ The percentile rank of this work's citation count compared to other works published in the same year. Contains `min` and `max` values representing the percentile range. ### [](https://docs.openalex.org/api-entities/works/work-object#concepts) `concepts` _List:_ List of dehydrated [`Concept` objects](https://docs.openalex.org/api-entities/concepts/concept-object) . Each `Concept` object in the list also has one additional property: * `score` (_Float_): The strength of the connection between the work and this concept (higher is stronger). This number is produced by AWS Sagemaker, in the last layer of the [machine learning model](https://github.com/ourresearch/openalex-concept-tagging) that assigns concepts. Concepts with a score of at least 0.3 are assigned to the work. However, ancestors of an assigned concept are also added to the work, even if the ancestor scores are below 0.3. Because ancestor concepts are assigned to works, you may see concepts in works with very low scores, even some zero scores. ### [](https://docs.openalex.org/api-entities/works/work-object#corresponding_author_ids) `corresponding_author_ids` _List:_ [OpenAlex IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) of any authors for which [authorships.is\_corresponding](https://docs.openalex.org/api-entities/works/work-object/authorship-object#is_corresponding) is `true`. ### [](https://docs.openalex.org/api-entities/works/work-object#corresponding_institution_ids) `corresponding_institution_ids` _List:_ [OpenAlex IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) of any institutions found within an `authorship` for which [authorships.is\_corresponding](https://docs.openalex.org/api-entities/works/work-object/authorship-object#is_corresponding) is `true`. ### [](https://docs.openalex.org/api-entities/works/work-object#countries_distinct_count) `countries_distinct_count` _Integer:_ Number of distinct `country_codes` among the [`authorships`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) for this work. ### [](https://docs.openalex.org/api-entities/works/work-object#counts_by_year) `counts_by_year` _List:_ [`Works.cited_by_count`](https://docs.openalex.org/api-entities/works/work-object#cited_by_count) for each of the last ten years, binned by year. To put it another way: each year, you can see how many times this work was cited. Any citations older than ten years old aren't included. Years with zero citations have been removed so you will need to add those in if you need them. ### [](https://docs.openalex.org/api-entities/works/work-object#created_date) `created_date` _String:_ The date this `Work` object was created in the OpenAlex dataset, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. ### [](https://docs.openalex.org/api-entities/works/work-object#display_name) `display_name` _String:_ Exactly the same as [`Work.title`](https://docs.openalex.org/api-entities/works/work-object#title) . It's useful for `Work`s to include a `display_name` property, since all the other entities have one. ### [](https://docs.openalex.org/api-entities/works/work-object#doi) `doi` _String:_ The DOI for the work. This is the [Canonical External ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#canonical-external-ids) for works. Occasionally, a work has more than one DOI--for example, there might be one DOI for a preprint version hosted on [bioRxiv](https://www.biorxiv.org/) , and another DOI for the [published version](https://docs.openalex.org/api-entities/works/work-object#version) . However, this field always has just one DOI, the DOI for the published work. ### [](https://docs.openalex.org/api-entities/works/work-object#fwci) `fwci` _Float:_ The Field-weighted Citation Impact (FWCI), calculated for a work as the ratio of citations received / citations expected in the year of publications and three following years. Learn more in the reference article: [Field Weighted Citation Impact (FWCI)](https://help.openalex.org/hc/en-us/articles/24735753007895-Field-Weighted-Citation-Impact-FWCI) . ### [](https://docs.openalex.org/api-entities/works/work-object#funders) `funders` _List:_ List of dehydrated [`Funder`](https://docs.openalex.org/api-entities/funders/funder-object) objects representing the funders of this work. This replaces the older `grants` property, which has been removed. The new `funders` and [`awards`](https://docs.openalex.org/api-entities/works/work-object#awards) properties provide much more comprehensive funding data. ### [](https://docs.openalex.org/api-entities/works/work-object#grants-deprecated) `grants` (deprecated) The `grants` property has been removed and replaced by [`funders`](https://docs.openalex.org/api-entities/works/work-object#funders) and [`awards`](https://docs.openalex.org/api-entities/works/work-object#awards) , which provide much more comprehensive funding data. ### [](https://docs.openalex.org/api-entities/works/work-object#has_content) `has_content` _Object:_ Information about available full-text content for this work. This field is for experimental internal use and is likely to disappear without notice. * `pdf`: _Boolean_ — whether a PDF is available * `grobid_xml`: _Boolean_ — whether GROBID-parsed XML is available ### [](https://docs.openalex.org/api-entities/works/work-object#host_venue-deprecated) `host_venue` (deprecated) The `host_venue` and `alternate_host_venues` properties have been deprecated in favor of [`primary_location`](https://docs.openalex.org/api-entities/works/work-object#primary_location) and [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) . The attributes `host_venue` and `alternate_host_venues` are no longer available in the Work object, and trying to access them in filters or group-bys will return an error. ### [](https://docs.openalex.org/api-entities/works/work-object#id) `id` _String:_ The [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for this work. ### [](https://docs.openalex.org/api-entities/works/work-object#ids) `ids` _Object:_ All the external identifiers that we know about for this work. IDs are expressed as URIs whenever possible. Possible ID types: * `doi` (_String:_ The [DOI](https://en.wikipedia.org/wiki/Digital_object_identifier) . Same as [`Work.doi`](https://docs.openalex.org/api-entities/works/work-object#title) ) * `mag` (_Integer:_ the [Microsoft Academic Graph](https://www.microsoft.com/en-us/research/project/microsoft-academic-graph/) ID) * `openalex` (_String:_ The [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) . Same as [`Work.id`](https://docs.openalex.org/api-entities/works/work-object#id) ) * `pmid` (_String:_ The [Pubmed Identifier](https://en.wikipedia.org/wiki/PubMed#PubMed_identifier) ) * `pmcid` (_String_: the [Pubmed Central identifier](https://www.ncbi.nlm.nih.gov/pmc/about/public-access-info/) ) Most works are missing one or more ID types (either because we don't know the ID, or because it was never assigned). Keys for `null` IDs are not displayed. ### [](https://docs.openalex.org/api-entities/works/work-object#indexed_in) `indexed_in` _List:_ The sources this work is indexed in. Possible values: `arxiv`, `crossref`, `doaj`, `pubmed`. ### [](https://docs.openalex.org/api-entities/works/work-object#institutions_distinct_count) `institutions_distinct_count` _Integer:_ Number of distinct [`institutions`](https://docs.openalex.org/api-entities/institutions) among the [`authorships`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) for this work. ### [](https://docs.openalex.org/api-entities/works/work-object#is_paratext) `is_paratext` _Boolean:_ True if we think this work is [paratext](https://en.wikipedia.org/wiki/Paratext) . In our context, paratext is stuff that's in a scholarly venue (like a journal) but is _about the venue_ rather than a scholarly work properly speaking. Some examples and nonexamples: * **yep it's paratext**: front cover, back cover, table of contents, editorial board listing, issue information, masthead. * **no, not paratext**: research paper, dataset, letters to the editor, figures Turns out there is a lot of paratext in registries like Crossref. That's not a bad thing... but we've found that it's good to have a way to filter it out. We determine `is_paratext` algorithmically using title heuristics. ### [](https://docs.openalex.org/api-entities/works/work-object#is_retracted) `is_retracted` _Boolean:_ True if we know this work has been retracted. We identify works that have been retracted using the public [Retraction Watch database](https://doi.org/10.13003/c23rw1d9) , a public resource made possible by a partnership between Crossref and The Center for Scientific Integrity. ### [](https://docs.openalex.org/api-entities/works/work-object#is_xpac) `is_xpac` _Boolean:_ True if this work is part of the XPAC (Expansion Pack) dataset. XPAC works are the 190+ million works added with the [Walden update](https://blog.openalex.org/openalex-rewrite-walden-launch/) . These are primarily datasets and records from individual repositories. The data quality on XPAC works is generally not as high as on other works, but it will improve over time. By default, XPAC works are excluded from API results. To include them, use the [`include_xpac=true`](https://docs.openalex.org/how-to-use-the-api/xpac) parameter. For more details, see the [XPAC documentation](https://docs.openalex.org/how-to-use-the-api/xpac) and the [Walden release notes](https://docs.google.com/document/d/1SPZ7QFcPddCHYt1pZP1UCIuqbfBY22lSHwgPA8RQyUY/edit?tab=t.0) . ### [](https://docs.openalex.org/api-entities/works/work-object#keywords) `keywords` _List of objects:_ Short phrases identified based on works' Topics. For background on how Keywords are identified, see [the Keywords page at OpenAlex help pages](https://help.openalex.org/how-it-works/keywords) . The score for each keyword represents the similarity score of that keyword to the title and abstract text of the work. We provide keywords for all keywords with scores above a certain threshold. ### [](https://docs.openalex.org/api-entities/works/work-object#language) `language` _String:_ The language of the work in [ISO 639-1 format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) . The language is automatically detected using the information we have about the work. We use the [langdetect](https://pypi.org/project/langdetect/) software library on the words in the work's abstract, or the title if we do not have the abstract. The source code for this procedure is [here.](https://github.com/ourresearch/openalex-guts/blob/54471c6c8e3c59662c4a4d9c37320af7b1667b2b/models/work.py#LL1102C1-L1102C1) Keep in mind that this method is not perfect, and that in some cases the language of the title or abstract could be different from the body of the work. A few things to keep in mind about this: * We don't always assign a language if we do not have enough words available to accurately guess. * We report the language of the metadata, not the full text. For example, if a work is in French, but the title and abstract are in English, we report the language as English. * In some cases, abstracts are in two different languages. Unfortunately, when this happens, what we report will not be accurate. ### [](https://docs.openalex.org/api-entities/works/work-object#locations) `locations` _List:_ A list of [`Location`](https://docs.openalex.org/api-entities/works/work-object/location-object) objects describing all unique places where this work lives. ### [](https://docs.openalex.org/api-entities/works/work-object#locations_count) `locations_count` _Integer:_ Number of [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) for this work. ### [](https://docs.openalex.org/api-entities/works/work-object#mesh) `mesh` _List:_ List of [MeSH](https://www.nlm.nih.gov/mesh/meshhome.html) tag objects. Only works found in [PubMed](https://pubmed.ncbi.nlm.nih.gov/) have MeSH tags; for all other works, this is an empty list. ### [](https://docs.openalex.org/api-entities/works/work-object#open_access) `open_access` _Object:_ Information about the access status of this work, as an [`OpenAccess`](https://docs.openalex.org/api-entities/works/work-object#the-openaccess-object) object. ### [](https://docs.openalex.org/api-entities/works/work-object#primary_location) `primary_location` _Object:_ A [`Location`](https://docs.openalex.org/api-entities/works/work-object/location-object) object with the primary location of this work. The `primary_location` is where you can find the best (closest to the [version of record](https://en.wikipedia.org/wiki/Version_of_record) ) copy of this work. For a peer-reviewed journal article, this would be a full text published version, hosted by the publisher at the article's DOI URL. ### [](https://docs.openalex.org/api-entities/works/work-object#primary_topic) `primary_topic` _Object_ The top ranked [`Topic`](https://docs.openalex.org/api-entities/topics) for this work. This is the same as the first item in [`Work.topics`](https://docs.openalex.org/api-entities/works/work-object#topics) . ### [](https://docs.openalex.org/api-entities/works/work-object#publication_date) `publication_date` _String:_ The day when this work was published, formatted as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date. Where different publication dates exist, we usually select the earliest available date of electronic publication. This date applies to the version found at [`Work.url`](https://docs.openalex.org/api-entities/works/work-object#url) . The other versions, found in [`Work.locations`](https://docs.openalex.org/api-entities/works/work-object#locations) , may have been published at different (earlier) dates. ### [](https://docs.openalex.org/api-entities/works/work-object#publication_year) `publication_year` _Integer:_ The year this work was published. This year applies to the version found at [`Work.url`](https://docs.openalex.org/api-entities/works/work-object#url) . The other versions, found in [`Work.locations`](https://docs.openalex.org/api-entities/works/work-object#locations) , may have been published in different (earlier) years. ### [](https://docs.openalex.org/api-entities/works/work-object#referenced_works) `referenced_works` _List:_ [OpenAlex IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for works that this work cites. These are citations that go _from_ this work out _to_ another work: This work ➞ Other works. ### [](https://docs.openalex.org/api-entities/works/work-object#referenced_works_count) `referenced_works_count` _Integer:_ The number of works that this work cites. This is the length of the [`referenced_works`](https://docs.openalex.org/api-entities/works/work-object#referenced_works) list. ### [](https://docs.openalex.org/api-entities/works/work-object#related_works) `related_works` _List:_ [OpenAlex IDs](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for works related to this work. Related works are computed algorithmically; the algorithm finds recent papers with the most concepts in common with the current paper. ### [](https://docs.openalex.org/api-entities/works/work-object#sustainable_development_goals) `sustainable_development_goals` _List:_ List of objects The United Nations' [17 Sustainable Development Goals](https://sdgs.un.org/goals) are a collection of goals at the heart of a global "shared blueprint for peace and prosperity for people and the planet." We use a machine learning model to tag works with their relevance to these goals based on our [OpenAlex SDG Classifier](https://github.com/ourresearch/openalex-sdg-classifier) , an mBERT machine learning model developed by the [Aurora Universities Network](https://aurora-universities.eu/sdg-research/) . The `score` represents the model's predicted probability of the work's relevance for a particular goal. We display all of the SDGs with a prediction score higher than 0.4. ### [](https://docs.openalex.org/api-entities/works/work-object#topics) `topics` _List:_ List of objects The top ranked [`Topics`](https://docs.openalex.org/api-entities/topics) for this work. We provide up to 3 topics per work. ### [](https://docs.openalex.org/api-entities/works/work-object#title) `title` _String:_ The title of this work. This is exactly the same as [`Work.display_name`](https://docs.openalex.org/api-entities/works/work-object#display_name) . We include both attributes with the same information because we want all entities to have a `display_name`, but there's a longstanding tradition of calling this the "title," so we figured you'll be expecting works to have it as a property. ### [](https://docs.openalex.org/api-entities/works/work-object#type) `type` _String:_ The type of the work. You can see all of the different types along with their counts in the OpenAlex API here: [`https://api.openalex.org/works?group_by=type`](https://api.openalex.org/works?group_by=type) . Most works are type `article`. This includes what was Crossref calls `journal-article`, `proceedings-article`, and `posted-content`. We consider all of these to be `article` type works, and the distinctions between them to be more about where they are published or hosted: * Journal articles will have a [`primary_location.source.type`](https://docs.openalex.org/api-entities/works/work-object/location-object#source) of `journal` * Conference proceedings will have a [`primary_location.source.type`](https://docs.openalex.org/api-entities/works/work-object/location-object#source) of `conference` * Preprints or "posted content" will have a [`primary_location.version`](https://docs.openalex.org/api-entities/works/work-object/location-object#version) of `submittedVersion` (Note that distinguishing between journals and conferences is a hard problem, one we often get wrong. We are working on improving this, but we also point out that the two have a lot of overlap in terms of their roles as hosts of research publications.) Works that are hosted primarily on a preprint, or that are identified speicifically as preprints in the metadata we receive, are assigned the type `preprint` rather than `article`. Works that represent stuff that is _about_ the venue (such as a journal)—rather than a scholarly work properly speaking—have type `paratext`. These include things like front-covers, back-covers, tables of contents, and the journal itself (e.g., `https://openalex.org/W4232230324`). We also have types for `letter` , `editorial` , `erratum` (corrections), `libguides` , `supplementary-materials` , and `review` (currently, articles that come from journals that exclusively publish review articles). Coverage is low on these but will improve. Other work types follow the Crossref "type" controlled vocabulary—see [`type_crossref`](https://docs.openalex.org/api-entities/works/work-object#type_crossref) . ### [](https://docs.openalex.org/api-entities/works/work-object#updated_date) `updated_date` _String:_ The last time anything in this `Work` object changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string (in UTC). This date is updated for _any change at all_, including increases in various counts. [](https://docs.openalex.org/api-entities/works/work-object#the-openaccess-object) The `OpenAccess` object --------------------------------------------------------------------------------------------------------------- The `OpenAccess` object describes access options for a given work. It's only found as part of the `Work` object. ### [](https://docs.openalex.org/api-entities/works/work-object#any_repository_has_fulltext) `any_repository_has_fulltext` _Boolean:_ `True` if any of this work's [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) has `location.is_oa=true` and `location.source.type=repository`. Use case: researchers want to track Green OA, using a definition of "any repository hosts this." OpenAlex's definition (as used in [`oa_status`](https://docs.openalex.org/api-entities/works/work-object#oa_status) ) doesn't support this, because as soon as there's a publisher-hosted copy (bronze, hybrid, or gold), oa\_status is set to that publisher-hosted status. So there's a lot of repository-hosted content that the `oa_status` can't tell you about. Our [State of OA paper](https://peerj.com/articles/4375/) calls this "shadowed Green." This feature makes it possible to track shadowed Green. ### [](https://docs.openalex.org/api-entities/works/work-object#is_oa) `is_oa` _Boolean:_ `True` if this work is Open Access (OA). There are [many ways to define OA](https://peerj.com/articles/4375/#literature-review) . OpenAlex uses a broad definition: having a URL where you can read the fulltext of this work without needing to pay money or log in. You can use the [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) and [`oa_status`](https://docs.openalex.org/api-entities/works/work-object#oa_status) fields to narrow your results further, accommodating any definition of OA you like. ### [](https://docs.openalex.org/api-entities/works/work-object#oa_status) `oa_status` _String:_ The Open Access (OA) status of this work. Possible values are: * [`**diamond**`](https://en.wikipedia.org/wiki/Diamond_open_access) : Published in a fully OA journal—one that is indexed by the [DOAJ](https://doaj.org/) or that we have determined to be OA—with no article processing charges (i.e., free for both readers and authors). * `**gold**`: Published in a fully OA journal. * `**green**`: Toll-access on the publisher landing page, but there is a free copy in an [OA repository](https://en.wikipedia.org/wiki/Open-access_repository) . * `**hybrid**`: Free under an [open license](https://support.unpaywall.org/support/solutions/articles/44002063718-what-is-an-oa-license-) in a toll-access journal. * `**bronze**`: Free to read on the publisher landing page, but without any identifiable license. * `**closed**`: All other articles. ### [](https://docs.openalex.org/api-entities/works/work-object#oa_url) `oa_url` _String:_ The best Open Access (OA) URL for this work. Although there are [many ways to define OA](https://peerj.com/articles/4375/#literature-review) , in this context an OA URL is one where you can read the fulltext of this work without needing to pay money or log in. The "best" such URL is the one closest to the version of record. This URL might be a direct link to a PDF, or it might be to a landing page that links to the free PDF [PreviousWorks](https://docs.openalex.org/api-entities/works) [NextAuthorship object](https://docs.openalex.org/api-entities/works/work-object/authorship-object) Last updated 22 days ago * [abstract\_inverted\_index](https://docs.openalex.org/api-entities/works/work-object#abstract_inverted_index) * [alternate\_host\_venues (deprecated)](https://docs.openalex.org/api-entities/works/work-object#alternate_host_venues-deprecated) * [awards](https://docs.openalex.org/api-entities/works/work-object#awards) * [authorships](https://docs.openalex.org/api-entities/works/work-object#authorships) * [apc\_list](https://docs.openalex.org/api-entities/works/work-object#apc_list) * [apc\_paid](https://docs.openalex.org/api-entities/works/work-object#apc_paid) * [best\_oa\_location](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [biblio](https://docs.openalex.org/api-entities/works/work-object#biblio) * [citation\_normalized\_percentile](https://docs.openalex.org/api-entities/works/work-object#citation_normalized_percentile) * [cited\_by\_count](https://docs.openalex.org/api-entities/works/work-object#cited_by_count) * [cited\_by\_percentile\_year](https://docs.openalex.org/api-entities/works/work-object#cited_by_percentile_year) * [concepts](https://docs.openalex.org/api-entities/works/work-object#concepts) * [corresponding\_author\_ids](https://docs.openalex.org/api-entities/works/work-object#corresponding_author_ids) * [corresponding\_institution\_ids](https://docs.openalex.org/api-entities/works/work-object#corresponding_institution_ids) * [countries\_distinct\_count](https://docs.openalex.org/api-entities/works/work-object#countries_distinct_count) * [counts\_by\_year](https://docs.openalex.org/api-entities/works/work-object#counts_by_year) * [created\_date](https://docs.openalex.org/api-entities/works/work-object#created_date) * [display\_name](https://docs.openalex.org/api-entities/works/work-object#display_name) * [doi](https://docs.openalex.org/api-entities/works/work-object#doi) * [fwci](https://docs.openalex.org/api-entities/works/work-object#fwci) * [funders](https://docs.openalex.org/api-entities/works/work-object#funders) * [grants (deprecated)](https://docs.openalex.org/api-entities/works/work-object#grants-deprecated) * [has\_content](https://docs.openalex.org/api-entities/works/work-object#has_content) * [host\_venue (deprecated)](https://docs.openalex.org/api-entities/works/work-object#host_venue-deprecated) * [id](https://docs.openalex.org/api-entities/works/work-object#id) * [ids](https://docs.openalex.org/api-entities/works/work-object#ids) * [indexed\_in](https://docs.openalex.org/api-entities/works/work-object#indexed_in) * [institutions\_distinct\_count](https://docs.openalex.org/api-entities/works/work-object#institutions_distinct_count) * [is\_paratext](https://docs.openalex.org/api-entities/works/work-object#is_paratext) * [is\_retracted](https://docs.openalex.org/api-entities/works/work-object#is_retracted) * [is\_xpac](https://docs.openalex.org/api-entities/works/work-object#is_xpac) * [keywords](https://docs.openalex.org/api-entities/works/work-object#keywords) * [language](https://docs.openalex.org/api-entities/works/work-object#language) * [locations](https://docs.openalex.org/api-entities/works/work-object#locations) * [locations\_count](https://docs.openalex.org/api-entities/works/work-object#locations_count) * [mesh](https://docs.openalex.org/api-entities/works/work-object#mesh) * [open\_access](https://docs.openalex.org/api-entities/works/work-object#open_access) * [primary\_location](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [primary\_topic](https://docs.openalex.org/api-entities/works/work-object#primary_topic) * [publication\_date](https://docs.openalex.org/api-entities/works/work-object#publication_date) * [publication\_year](https://docs.openalex.org/api-entities/works/work-object#publication_year) * [referenced\_works](https://docs.openalex.org/api-entities/works/work-object#referenced_works) * [referenced\_works\_count](https://docs.openalex.org/api-entities/works/work-object#referenced_works_count) * [related\_works](https://docs.openalex.org/api-entities/works/work-object#related_works) * [sustainable\_development\_goals](https://docs.openalex.org/api-entities/works/work-object#sustainable_development_goals) * [topics](https://docs.openalex.org/api-entities/works/work-object#topics) * [title](https://docs.openalex.org/api-entities/works/work-object#title) * [type](https://docs.openalex.org/api-entities/works/work-object#type) * [updated\_date](https://docs.openalex.org/api-entities/works/work-object#updated_date) * [The OpenAccess object](https://docs.openalex.org/api-entities/works/work-object#the-openaccess-object) * [any\_repository\_has\_fulltext](https://docs.openalex.org/api-entities/works/work-object#any_repository_has_fulltext) * [is\_oa](https://docs.openalex.org/api-entities/works/work-object#is_oa) * [oa\_status](https://docs.openalex.org/api-entities/works/work-object#oa_status) * [oa\_url](https://docs.openalex.org/api-entities/works/work-object#oa_url) Copy awards: [\ {\ id: "https://openalex.org/G5453342221",\ display_name: "Implementation of activities described in the Roadmap to Fusion during Horizon 2020 through a Joint programme of the members of the EUROfusion consortium",\ funder_award_id: "633053",\ funder_id: "https://openalex.org/F4320337670",\ funder_display_name: "H2020 Euratom",\ doi: "https://doi.org/10.3030/633053"\ }\ ] Copy authorships: [\ // first authorship object:\ {\ author_position: "middle",\ author: {\ id: "https://openalex.org/A5023888391",\ display_name: "Jason Priem",\ orcid: "https://orcid.org/0000-0001-6187-6610"\ },\ institutions: [\ {\ id: "https://openalex.org/I4200000001",\ display_name: "OurResearch",\ ror: "https://ror.org/02nr0ka47",\ country_code: "US",\ type: "nonprofit"\ }\ ],\ // other fields removed for brevity. See the Authorship object documentation\ },\ \ // more authorship objects go here\ ] Copy apc_payment: { value: 3200, currency: "USD", value_usd: 3200, provenance: "doaj" } Copy apc_payment: { value: 2250, currency: "EUR", value_usd: 2426, provenance: "openapc" } Copy best_oa_location: { is_oa: true, landing_page_url: "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1398957", pdf_url: null, source: { id: "https://openalex.org/S2764455111", display_name: "PubMed Central", issn_l: null, issn: null, host_organization: "https://openalex.org/I1299303238", type: "repository" }, license: null, version: "publishedVersion" } Copy biblio: { volume: "495", issue: "7442", first_page: "437", last_page: "440" } Copy citation_normalized_percentile: { value: 0.999948, is_in_top_1_percent: true, is_in_top_10_percent: true } Copy cited_by_count: 382 Copy cited_by_percentile_year: { min: 89, max: 96 } Copy concepts: [\ {\ id: "https://openalex.org/C71924100",\ wikidata: "https://www.wikidata.org/wiki/Q11190",\ display_name: "Medicine",\ level: 0,\ score: 0.9187037\ },\ {\ id: "https://openalex.org/C3007834351",\ wikidata: "https://www.wikidata.org/wiki/Q82069695",\ display_name: "Severe acute respiratory syndrome coronavirus 2 (SARS-CoV-2)",\ level: 5,\ score: 0.8070164\ },\ ...\ {\ id: "https://openalex.org/C191935318",\ wikidata: "https://www.wikidata.org/wiki/Q148",\ display_name: "China",\ level: 2,\ score: 0.5948172\ },\ ...\ {\ id: "https://openalex.org/C121608353",\ wikidata: "https://www.wikidata.org/wiki/Q12078",\ display_name: "Cancer",\ level: 2,\ score: 0.46887803\ },\ ...\ {\ id: "https://openalex.org/C17744445",\ wikidata: "https://www.wikidata.org/wiki/Q36442",\ display_name: "Political science",\ level: 0,\ score: 0\ }\ ] Copy corresponding_author_ids: ["https://openalex.org/A5004365451"] Copy corresponding_institution_ids: ["https://openalex.org/I4210123613"] Copy countries_distinct_count: 4 Copy counts_by_year: [\ {\ year: 2022,\ cited_by_count: 8\ },\ {\ year: 2021,\ cited_by_count: 252\ },\ ...\ {\ year: 2012,\ cited_by_count: 79\ }\ ] Copy created_date: "2017-08-08" Copy display_name: "The state of OA: a large-scale analysis of the prevalence and impact of Open Access articles", Copy doi: "https://doi.org/10.7717/peerj.4375" Copy fwci: 76.992 Copy funders: [\ {\ id: "https://openalex.org/F4320306076",\ display_name: "National Science Foundation",\ ror: "https://ror.org/021nxhr62"\ },\ {\ id: "https://openalex.org/F4320306084",\ display_name: "U.S. Department of Energy",\ ror: "https://ror.org/01bj3aw27"\ }\ ] Copy has_content: { pdf: true, grobid_xml: false } Copy id: "https://openalex.org/W2741809807" Copy ids: { openalex: "https://openalex.org/W2741809807", doi: "https://doi.org/10.7717/peerj.4375", mag: 2741809807, pmid: "https://pubmed.ncbi.nlm.nih.gov/29456894" } Copy indexed_in: [\ "arxiv", "crossref", "pubmed"\ ] Copy institutions_distinct_count: 4 Copy is_paratext: false Copy is_retracted: false Copy is_xpac: false Copy [\ {\ id: "https://openalex.org/keywords/global-seaweed-distribution",\ display_name: "Global Seaweed Distribution",\ score: 0.559386\ },\ {\ id: "https://openalex.org/keywords/climate-change-impacts",\ display_name: "Climate Change Impacts",\ score: 0.535795\ },\ {\ id: "https://openalex.org/keywords/ecosystem-resilience",\ display_name: "Ecosystem Resilience",\ score: 0.502789\ }\ ] Copy language: "en" Copy locations: [ \ {\ is_oa: true,\ landing_page_url: "https://doi.org/10.1073/pnas.17.6.401",\ pdf_url: "http://www.pnas.org/content/17/6/401.full.pdf",\ source: {\ id: "https://openalex.org/S125754415",\ display_name: "Proceedings of the National Academy of Sciences of the United States of America",\ issn_l: "0027-8424",\ issn: ["1091-6490", "0027-8424"],\ host_organization: "https://openalex.org/P4310320052",\ type: "journal"\ },\ license: null,\ version: "publishedVersion"\ },\ {\ is_oa: true,\ landing_page_url: "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1076072",\ pdf_url: null,\ source: {\ id: "https://openalex.org/S2764455111",\ display_name: "PubMed Central",\ issn_l: null,\ issn: null,\ host_organization: "https://openalex.org/I1299303238",\ type: "repository"\ },\ license: null,\ version: "publishedVersion"\ }\ ] Copy locations_count: 3 Copy mesh: [\ {\ descriptor_ui: "D017712",\ descriptor_name: "Peer Review, Research",\ qualifier_ui: "Q000379",\ qualifier_name: "methods",\ is_major_topic: false\ },\ {\ descriptor_ui: "D017712",\ descriptor_name: "Peer Review, Research",\ qualifier_ui: "Q000592",\ qualifier_name: "standards",\ is_major_topic: true\ }\ ] Copy open_access: { is_oa: true, oa_status: "gold", oa_url: "https://peerj.com/articles/4375.pdf", any_repository_has_fulltext: true }, Copy primary_location: { is_oa: true, landing_page_url: "https://doi.org/10.1073/pnas.17.6.401", pdf_url: "http://www.pnas.org/content/17/6/401.full.pdf", source: { id: "https://openalex.org/S125754415", display_name: "Proceedings of the National Academy of Sciences of the United States of America", issn_l: "0027-8424", issn: ["1091-6490", "0027-8424"], host_organization: "https://openalex.org/P4310320052", type: "journal" }, license: null, version: "publishedVersion" } Copy primary_topic: { id: "https://openalex.org/T12419", display_name: "Analysis of Cardiac and Respiratory Sounds", score: 0.9997, subfield: { id: "https://openalex.org/subfields/2740", display_name: "Pulmonary and Respiratory Medicine" }, field: { id: "https://openalex.org/fields/27", display_name: "Medicine" }, domain: { id: "https://openalex.org/domains/4", display_name: "Health Sciences" } } Copy publication_date: "2018-02-13" Copy publication_year: 2018 Copy referenced_works: [\ "https://openalex.org/W2753353163",\ "https://openalex.org/W2785823074",\ "https://openalex.org/W2511661767",\ "https://openalex.org/W2115339903",\ "https://openalex.org/W2031754690"\ ] Copy referenced_works_count: 5 Copy related_works: [\ "https://openalex.org/W2753353163",\ "https://openalex.org/W2785823074",\ "https://openalex.org/W2511661767",\ "https://openalex.org/W2115339903",\ "https://openalex.org/W2031754690",\ ] Copy sustainable_development_goals: [\ {\ id: "https://metadata.un.org/sdg/3",\ display_name: "Good health and well-being",\ score: 0.95\ }\ ] Copy topics: [\ {\ id: "https://openalex.org/T12419",\ display_name: "Analysis of Cardiac and Respiratory Sounds",\ score: 0.9997,\ subfield: {\ id: "https://openalex.org/subfields/2740",\ display_name: "Pulmonary and Respiratory Medicine"\ },\ field: {\ id: "https://openalex.org/fields/27",\ display_name: "Medicine"\ },\ domain: {\ id: "https://openalex.org/domains/4",\ display_name: "Health Sciences"\ }\ },\ ...\ ] Copy title: "The state of OA: a large-scale analysis of the prevalence and impact of Open Access articles", Copy type: "article" Copy updated_date: "2022-01-02T00:22:35.180390" Copy any_repository_has_fulltext: true Copy is_oa: true Copy oa_status: "gold" Copy oa_url: "https://peerj.com/articles/4375.pdf" --- # Filter works | OpenAlex technical documentation It's easy to filter works with the `filter` parameter: * Get works where the publication year is 2020 [`https://api.openalex.org/works?filter=publication\_year:2020`](https://api.openalex.org/works?filter=publication_year:2020) In this example the filter is `publication_year` and the value is 2020. It's best to [read about filters](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists) before trying these out. It will show you how to combine filters and build an AND, OR, or negation query. [](https://docs.openalex.org/api-entities/works/filter-works#works-attribute-filters) `/works` attribute filters --------------------------------------------------------------------------------------------------------------------- You can filter using these attributes of the [`Work`](https://docs.openalex.org/api-entities/works/work-object) object (click each one to view their documentation on the `Work` object page): The `host_venue` and `alternate_host_venues` properties have been deprecated in favor of [`primary_location`](https://docs.openalex.org/api-entities/works/work-object#primary_location) and [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) . The attributes `host_venue` and `alternate_host_venues` are no longer available in the Work object, and trying to access them in filters or group-bys will return an error. * [`authorships.affiliations.institution_ids`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#affiliations) * [`authorships.author.id`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#author) (alias: `author.id`) — Authors for a work (OpenAlex ID) * [`authorships.author.orcid`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#author) (alias: `author.orcid`) — Authors for a work (ORCID) * [`authorships.countries`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#countries) * [`authorships.institutions.country_code`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) (alias: `institutions.country_code`) * [`authorships.institutions.id`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) (alias: `institutions.id`) — Institutions affiliated with the authors of a work (OpenAlex ID) * [`authorships.institutions.lineage`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) * [`authorships.institutions.ror`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) (alias: `institutions.ror`) — Institutions affiliated with the authors of a work (ROR ID) * [`authorships.institutions.type`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#institutions) * [`authorships.is_corresponding`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#is_corresponding) (alias: `is_corresponding`) — This filter marks whether or not we have corresponding author information for a given work * [`apc_list.value`](https://docs.openalex.org/api-entities/works/work-object#apc_list) * [`apc_list.currency`](https://docs.openalex.org/api-entities/works/work-object#apc_list) * [`apc_list.provenance`](https://docs.openalex.org/api-entities/works/work-object#apc_list) * [`apc_list.value_usd`](https://docs.openalex.org/api-entities/works/work-object#apc_list) * [`apc_paid.value`](https://docs.openalex.org/api-entities/works/work-object#apc_paid) * [`apc_paid.currency`](https://docs.openalex.org/api-entities/works/work-object#apc_paid) * [`apc_paid.provenance`](https://docs.openalex.org/api-entities/works/work-object#apc_paid) * [`apc_paid.value_usd`](https://docs.openalex.org/api-entities/works/work-object#apc_paid) * [`best_oa_location.is_accepted`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.is_published`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.license`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) — The Open Acess license for a work * [`best_oa_location.source.id`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.source.is_in_doaj`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.source.issn`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.source.host_organization`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.source.type`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`best_oa_location.version`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) * [`biblio.first_page`](https://docs.openalex.org/api-entities/works/work-object#biblio) * [`biblio.issue`](https://docs.openalex.org/api-entities/works/work-object#biblio) * [`biblio.last_page`](https://docs.openalex.org/api-entities/works/work-object#biblio) * [`biblio.volume`](https://docs.openalex.org/api-entities/works/work-object#biblio) * [`cited_by_count`](https://docs.openalex.org/api-entities/works/work-object#cited_by_count) * [`concepts.id`](https://docs.openalex.org/api-entities/works/work-object#concepts) (alias: `concept.id`) — The concepts associated with a work * [`concepts.wikidata`](https://docs.openalex.org/api-entities/works/work-object#concepts) * [`corresponding_author_ids`](https://docs.openalex.org/api-entities/works/work-object#corresponding_author_ids) — Corresponding authors for a work (OpenAlex ID) * [`corresponding_institution_ids`](https://docs.openalex.org/api-entities/works/work-object#corresponding_institution_ids) * [`countries_distinct_count`](https://docs.openalex.org/api-entities/works/work-object#countries_distinct_count) * [`doi`](https://docs.openalex.org/api-entities/works/work-object#doi) — The DOI (Digital Object Identifier) of a work * [`fulltext_origin`](https://docs.openalex.org/api-entities/works/work-object#fulltext_origin) * [`fwci`](https://docs.openalex.org/api-entities/works/work-object#fwci) * [`grants.award_id`](https://docs.openalex.org/api-entities/works/work-object#grants) — Award IDs for grants * [`grants.funder`](https://docs.openalex.org/api-entities/works/work-object#grants) — Funding organizations linked to grants for a work * [`has_fulltext`](https://docs.openalex.org/api-entities/works/work-object#has_fulltext) * [`ids.pmcid`](https://docs.openalex.org/api-entities/works/work-object#ids) * [`ids.pmid`](https://docs.openalex.org/api-entities/works/work-object#ids) (alias: `pmid`) * [`ids.openalex`](https://docs.openalex.org/api-entities/works/work-object#ids) (alias: `openalex`) — The OpenAlex ID for a work * [`ids.mag`](https://docs.openalex.org/api-entities/works/work-object#ids) (alias: `mag`) * [`indexed_in`](https://docs.openalex.org/api-entities/works/work-object#indexed_in) * [`institutions_distinct_count`](https://docs.openalex.org/api-entities/works/work-object#institutions_distinct_count) * [`is_paratext`](https://docs.openalex.org/api-entities/works/work-object#is_paratext) * [`is_retracted`](https://docs.openalex.org/api-entities/works/work-object#is_retracted) * [`keywords.keyword`](https://docs.openalex.org/api-entities/works/work-object#keywords) * [`language`](https://docs.openalex.org/api-entities/works/work-object#language) * [`locations.is_accepted`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.is_oa`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.is_published`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.license`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.source.id`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.source.is_core`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.source.is_in_doaj`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.source.issn`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.source.host_organization`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.source.type`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations.version`](https://docs.openalex.org/api-entities/works/work-object#locations) * [`locations_count`](https://docs.openalex.org/api-entities/works/work-object#locations_count) * [`open_access.any_repository_has_fulltext`](https://docs.openalex.org/api-entities/works/work-object#open_access) * [`open_access.is_oa`](https://docs.openalex.org/api-entities/works/work-object#open_access) (alias: `is_oa`) — Whether a work is Open Access * [`open_access.oa_status`](https://docs.openalex.org/api-entities/works/work-object#open_access) (alias: `oa_status`) — The Open Access status for a work (e.g., gold, green, hybrid, etc.) * [`primary_location.is_accepted`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.is_oa`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.is_published`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.license`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.id`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.is_core`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.is_in_doaj`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.issn`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.host_organization`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.source.type`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_location.version`](https://docs.openalex.org/api-entities/works/work-object#primary_location) * [`primary_topic.id`](https://docs.openalex.org/api-entities/works/work-object#primary_topic) * [`primary_topic.domain.id`](https://docs.openalex.org/api-entities/works/work-object#primary_topic) * [`primary_topic.field.id`](https://docs.openalex.org/api-entities/works/work-object#primary_topic) * [`primary_topic.subfield.id`](https://docs.openalex.org/api-entities/works/work-object#primary_topic) * [`publication_year`](https://docs.openalex.org/api-entities/works/work-object#publication_year) * [`publication_date`](https://docs.openalex.org/api-entities/works/work-object#publication_date) * [`sustainable_development_goals.id`](https://docs.openalex.org/api-entities/works/work-object#sustainable_development_goals) * [`topics.id`](https://docs.openalex.org/api-entities/works/work-object#topics) * [`topics.domain.id`](https://docs.openalex.org/api-entities/works/work-object#topics) * [`topics.field.id`](https://docs.openalex.org/api-entities/works/work-object#topics) * [`topics.subfield.id`](https://docs.openalex.org/api-entities/works/work-object#topics) * [`type`](https://docs.openalex.org/api-entities/works/work-object#type) * [`type_crossref`](https://docs.openalex.org/api-entities/works/work-object#type_crossref) Want to filter by the `display_name` of an associated entity (author, institution, source, etc.)? [See here.](https://docs.openalex.org/api-entities/works/search-works#why-cant-i-search-by-name-of-related-entity-author-name-institution-name-etc.) [](https://docs.openalex.org/api-entities/works/filter-works#works-convenience-filters) `/works` convenience filters ------------------------------------------------------------------------------------------------------------------------- These filters aren't attributes of the [`Work`](https://docs.openalex.org/api-entities/works/work-object) object, but they're handy for solving some common use cases: #### [](https://docs.openalex.org/api-entities/works/filter-works#abstract.search) `abstract.search` Text search using abstracts Value: a search string Returns: works whose abstract includes the given string. See the [search page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) for details on the search algorithm used. * Get works with abstracts that mention "artificial intelligence": [`https://api.openalex.org/works?filter=abstract.search:artificial%20intelligence`](https://api.openalex.org/works?filter=abstract.search:artificial%20intelligence) #### [](https://docs.openalex.org/api-entities/works/filter-works#authors_count) `authors_count` Number of authors for a work Value: an Integer Returns: works with the chosen number of [`authorships`](https://docs.openalex.org/api-entities/works/work-object#authorships) objects (authors). You can use the inequality filter to select a range, such as `authors_count:>5`_._ * Get works that have exactly one author [`https://api.openalex.org/works?filter=authors\_count:1`](https://api.openalex.org/works?filter=authors_count:1) #### [](https://docs.openalex.org/api-entities/works/filter-works#authorships.institutions.continent-alias-institutions.continent) `authorships.institutions.continent` (alias: `institutions.continent`) Value: a String with a valid [continent filter](https://docs.openalex.org/api-entities/geo/continents#filter-by-continent) Returns: works where at least _one_ of the author's institutions is in the chosen continent. * Get works where at least one author's institution in each work is located in Europe [`https://api.openalex.org/works?filter=authorships.institutions.continent:europe`](https://api.openalex.org/works?filter=authorships.institutions.continent:europe) #### [](https://docs.openalex.org/api-entities/works/filter-works#authorships.institutions.is_global_south-alias-institutions.is_global_south) `authorships.institutions.is_global_south` (alias: `institutions.is_global_south`) Value: a Boolean (`true` or `false`) Returns: works where at least _one_ of the author's institutions is in the Global South ([read more](https://docs.openalex.org/api-entities/geo/regions#global-south) ). * Get works where at least one author's institution is in the Global South [`https://api.openalex.org/works?filter=authorships.institutions.is\_global\_south:true`](https://api.openalex.org/works?filter=authorships.institutions.is_global_south:true) #### [](https://docs.openalex.org/api-entities/works/filter-works#best_open_version) `best_open_version` Value: a String with one of the following values: * `**any**`: This means that `best_oa_location.version` = `submittedVersion`, `acceptedVersion`, or `publishedVersion` * `**acceptedOrPublished**`: This means that `best_oa_location.version` can be `acceptedVersion` or `publishedVersion` * `**published**`: This means that `best_oa_location.version` = `publishedVersion` Returns: works that meet the above criteria for [`best_oa_location`](https://docs.openalex.org/api-entities/works/work-object#best_oa_location) . * Get works whose `best_oa_location` is a submitted, accepted, or published version: [`https://api.openalex.org/works?filter=best_open_version:any`](https://api.openalex.org/works?filter=best_open_version:any) \`\` #### [](https://docs.openalex.org/api-entities/works/filter-works#cited_by) `cited_by` Value: the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for a given work Returns: works found in the given work's [`referenced_works`](https://docs.openalex.org/api-entities/works/work-object#referenced_works) section. You can think of this as **outgoing citations**. * Get works cited by [`https://openalex.org/W2766808518`](https://openalex.org/W2766808518) : [`https://api.openalex.org/works?filter=cited_by:W2766808518`](https://api.openalex.org/works?filter=cited_by:W2766808518) #### [](https://docs.openalex.org/api-entities/works/filter-works#cites) `cites` Value: the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for a given work Returns: works that cite the given work. This is works that have the given OpenAlex ID in the [`referenced_works`](https://docs.openalex.org/api-entities/works/work-object#referenced_works) section. You can think of this as **incoming citations**. * Get works that cite [`https://openalex.org/W2741809807`](https://openalex.org/W2741809807) : [`https://api.openalex.org/works?filter=cites:W2741809807`](https://api.openalex.org/works?filter=cites:W2741809807) \`\` The number of results returned by this filter may be slightly higher than the work's[`cited_by_count`](https://docs.openalex.org/api-entities/works/work-object#cited_by_count) due to a timing lag in updating that field. #### [](https://docs.openalex.org/api-entities/works/filter-works#concepts_count) `concepts_count` Value: an Integer Returns: works with the chosen number of [`concepts`](https://docs.openalex.org/api-entities/works/work-object#concepts) . * Get works with at least three concepts assigned [`https://api.openalex.org/works?filter=concepts\_count:>2`](https://api.openalex.org/works?filter=concepts_count:%3E2) #### [](https://docs.openalex.org/api-entities/works/filter-works#default.search) `default.search` Text search across titles, abstracts, and full text of works Value: a search string This works the same as using the [`search` parameter](https://docs.openalex.org/api-entities/works/search-works#search-works) for Works. #### [](https://docs.openalex.org/api-entities/works/filter-works#display_name.search-alias-title.search) `display_name.search` (alias: `title.search`) Text search across titles for works Value: a search string Returns: works whose[`display_name`](https://docs.openalex.org/api-entities/works/work-object#display_name) (title) includes the given string; see the [search page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) for details. * Get works with titles that mention the word "wombat": [`https://api.openalex.org/works?filter=title.search:wombat`](https://api.openalex.org/works?filter=title.search:wombat) For most cases, you should use the [`search`](https://docs.openalex.org/api-entities/works/search-works#works-full-search) parameter instead of this filter, because it uses a better search algorithm and searches over abstracts as well as titles. #### [](https://docs.openalex.org/api-entities/works/filter-works#from_created_date) `from_created_date` Value: a date, formatted as `yyyy-mm-dd` Returns: works with [`created_date`](https://docs.openalex.org/api-entities/works/work-object#created_date) greater than or equal to the given date. This field requires an [OpenAlex Premium subscription to access. Click here to learn more.](https://openalex.org/pricing) * Get works created on or _after_ January 12th, 2023 (does not work without valid API key): [`https://api.openalex.org/works?filter=from_created_date:2023-01-12&api_key=myapikey`](https://api.openalex.org/works?filter=from_created_date:2023-01-12&api_key=myapikey) #### [](https://docs.openalex.org/api-entities/works/filter-works#from_publication_date) `from_publication_date` Value: a date, formatted as `yyyy-mm-dd` Returns: works with [`publication_date`](https://docs.openalex.org/api-entities/works/work-object#publication_date) greater than or equal to the given date. * Get works published on or _after_ March 14th, 2001: [`https://api.openalex.org/works?filter=from_publication_date:2001-03-14`](https://api.openalex.org/works?filter=from_publication_date:2001-03-14) Filtering by publication date is not a reliable way to retrieve recently updated and created works, due to the way publishers assign publication dates. Use `from_created_date` or `from_updated_date` to get the latest changes in OpenAlex. #### [](https://docs.openalex.org/api-entities/works/filter-works#from_updated_date) `from_updated_date` Value: a date, formatted as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date or date-time string (for example: "2020-05-17", "2020-05-17T15:30", or "2020-01-02T00:22:35.180390"). Returns: works with [`updated_date`](https://docs.openalex.org/api-entities/works/work-object#updated_date) greater than or equal to the given date. This field requires an [OpenAlex Premium subscription to access. Click here to learn more.](https://openalex.org/pricing) * Get works updated on or _after_ January 12th, 2023 (does not work without valid API key): [`https://api.openalex.org/works?filter=from_updated_date:2023-01-12&api_key=myapikey`](https://api.openalex.org/works?filter=from_updated_date:2023-01-12&api_key=myapikey) Learn more about using this filter to get the freshest data possible with our [Premium How-To](https://github.com/ourresearch/openalex-api-tutorials/blob/main/notebooks/getting-started/premium.ipynb) . #### [](https://docs.openalex.org/api-entities/works/filter-works#fulltext.search) `**fulltext.search**` Value: a search string Returns: works whose fulltext includes the given string. Fulltext search is available for a subset of works, obtained either from PDFs or [n-grams](https://docs.openalex.org/api-entities/works/get-n-grams) , see [`Work.has_fulltext`](https://docs.openalex.org/api-entities/works/work-object#has_fulltext) for more details. * Get works with fulltext that mention "climate change": [`https://api.openalex.org/works?filter=fulltext.search:climate%20change`](https://api.openalex.org/works?filter=fulltext.search:climate%20change) We combined some n-grams before storing them in our search database, so querying for an exact phrase using quotes does not always work well. #### [](https://docs.openalex.org/api-entities/works/filter-works#has_abstract) `has_abstract` Works that have an abstract available Value: a Boolean (`true` or `false`) Returns: works that have or lack an abstract, depending on the given value. * Get the works that have abstracts: [`https://api.openalex.org/works?filter=has_abstract:true`](https://api.openalex.org/works?filter=has_abstract:true) #### [](https://docs.openalex.org/api-entities/works/filter-works#has_doi) `has_doi` Value: a Boolean (`true` or `false`) Returns: works that have or lack a DOI, depending on the given value. It's especially useful for [grouping](https://docs.openalex.org/api-entities/works/group-works) . * Get the works that have no DOI assigned: [`https://api.openalex.org/works?filter=has_doi:false`](https://api.openalex.org/works?filter=has_doi:false) \`\` #### [](https://docs.openalex.org/api-entities/works/filter-works#has_oa_accepted_or_published_version) `has_oa_accepted_or_published_version` Value: a Boolean (`true` or `false`) Returns: works with at least one of the [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) has [`is_oa`](https://docs.openalex.org/api-entities/works/work-object/location-object#is_oa) \= true and [`version`](https://docs.openalex.org/api-entities/works/work-object#version) is acceptedVersion or publishedVersion. For Works that undergo peer review, like journal articles, this means there is a peer-reviewed OA copy somewhere. For some items, like books, a published version doesn't imply peer review, so they aren't quite synonymous. * Get works with an OA accepted or published copy [`https://api.openalex.org/works?filter=has_oa_accepted_or_published_version:true`](https://api.openalex.org/works?filter=has_oa_accepted_or_published_version:true) #### [](https://docs.openalex.org/api-entities/works/filter-works#has_oa_submitted_version) `has_oa_submitted_version` Value: a Boolean (`true` or `false`) Returns: works with at least one of the [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) has [`is_oa`](https://docs.openalex.org/api-entities/works/work-object/location-object#is_oa) \= true and [`version`](https://docs.openalex.org/api-entities/works/work-object#version) is submittedVersion. This is useful for finding works with preprints deposited somewhere. * Get works with an OA submitted copy: [`https://api.openalex.org/works?filter=has_oa_submitted_version:true`](https://api.openalex.org/works?filter=has_oa_submitted_version:true) \`\` #### [](https://docs.openalex.org/api-entities/works/filter-works#has_orcid) `has_orcid` Value: a Boolean (`true` or `false`) Returns: if `true` it returns works where at least one author or has an [ORCID ID](https://docs.openalex.org/api-entities/works/work-object#ids) . If `false`, it returns works where no authors have an ORCID ID. This is based on the `orcid` field within [`authorships.author`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#author) . Note that, sometimes, we assign ORCID using [author disambiguation](https://docs.openalex.org/api-entities/authors/author-disambiguation) , so this does not necessarily mean that the work itself has ORCID information. * Get the works where at least one author has an ORCID ID: [`https://api.openalex.org/works?filter=has_orcid:true`](https://api.openalex.org/works?filter=has_orcid:true) #### [](https://docs.openalex.org/api-entities/works/filter-works#has_pmcid) `has_pmcid` Value: a Boolean (`true` or `false`) Returns: works that have or lack a PubMed Central identifier ([`pmcid`](https://docs.openalex.org/api-entities/works/work-object#ids) ) depending on the given value. * Get the works that have a `pmcid`: [`https://api.openalex.org/works?filter=has_pmcid:true`](https://api.openalex.org/works?filter=has_pmcid:true) \`\` #### [](https://docs.openalex.org/api-entities/works/filter-works#has_pmid) `has_pmid` Value: a Boolean (`true` or `false`) Returns: works that have or lack a PubMed identifier ([`pmid`](https://docs.openalex.org/api-entities/works/work-object#ids) ), depending on the given value. * Get the works that have a `pmid`: [`https://api.openalex.org/works?filter=has_pmid:true`](https://api.openalex.org/works?filter=has_pmid:true) \`\` #### [](https://docs.openalex.org/api-entities/works/filter-works#has_ngrams-deprecated) `has_ngrams` (DEPRECATED) Works that have n-grams available to enable full-text search in OpenAlex. This filter has been deprecated. See instead: [`has_fulltext`](https://docs.openalex.org/api-entities/works/work-object#has_fulltext) . Value: a Boolean (`true` or `false`) Returns: works for which n-grams are available or unavailable, depending on the given value. N-grams power fulltext searches through the [`fulltext.search`](https://docs.openalex.org/api-entities/works/filter-works#fulltext.search) filter and the [`search`](https://docs.openalex.org/api-entities/works/search-works#works-full-search) parameter. * Get the works that have n-grams: [`https://api.openalex.org/works?filter=has_ngrams:true`](https://api.openalex.org/works?filter=has_ngrams:true) #### [](https://docs.openalex.org/api-entities/works/filter-works#has_references) `has_references` Value: a Boolean (`true` or `false`) Returns: works that have or lack [`referenced_works`](https://docs.openalex.org/api-entities/works/work-object#referenced_works) , depending on the given value. * Get the works that have references: [`https://api.openalex.org/works?filter=has_references:true`](https://api.openalex.org/works?filter=has_references:true) #### [](https://docs.openalex.org/api-entities/works/filter-works#journal) `journal` Value: the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for a given [source](https://docs.openalex.org/api-entities/sources/source-object) , where the source is [`type: journal`](https://docs.openalex.org/api-entities/sources/source-object#type) Returns: works where the chosen [source ID](https://docs.openalex.org/api-entities/sources/source-object#id) is the [`primary_location.source`](https://docs.openalex.org/api-entities/works/work-object#primary_location) . #### [](https://docs.openalex.org/api-entities/works/filter-works#locations.source.host_institution_lineage) `locations.source.host_institution_lineage` Value: the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for an [`Institution`](https://docs.openalex.org/api-entities/institutions) Returns: works where the given institution ID is in [`locations.source.host_organization_lineage`](https://docs.openalex.org/api-entities/sources/source-object#host_organization_lineage) * Get the works that have `https://openalex.org/I205783295` in their `host_organization_lineage`: [`https://api.openalex.org/works?filter=locations.source.host_institution_lineage:https://openalex.org/I205783295`](https://api.openalex.org/works?filter=locations.source.host_institution_lineage:https://openalex.org/I205783295) #### [](https://docs.openalex.org/api-entities/works/filter-works#locations.source.publisher_lineage) `locations.source.publisher_lineage` Value: the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for a [`Publisher`](https://docs.openalex.org/api-entities/publishers) Returns: works where the given publisher ID is in [`locations.source.host_organization_lineage`](https://docs.openalex.org/api-entities/sources/source-object#host_organization_lineage) * Get the works that have `https://openalex.org/P4310320547` in their `publisher_lineage`: [`https://api.openalex.org/works?filter=locations.source.publisher_lineage:https://openalex.org/P4310320547`](https://api.openalex.org/works?filter=locations.source.publisher_lineage:https://openalex.org/P4310320547) #### [](https://docs.openalex.org/api-entities/works/filter-works#mag_only) `mag_only` Value: a Boolean (`true` or `false`) Returns: works which came from MAG (Microsoft Academic Graph), and no other data sources. MAG was a project by Microsoft Research to catalog all of the scholarly content on the internet. After it was discontinued in 2021, OpenAlex built upon the data MAG had accumulated, connecting and expanding it using [a variety of other sources](https://help.openalex.org/hc/en-us/articles/24347019383191-Where-do-works-in-OpenAlex-come-from) . The methods that MAG used to identify and aggregate scholarly content were quite different from most of our other sources, and so the content inherited from MAG, especially works that we did not connect with data from other sources, can look different from other works. While it's great to have these MAG-only works available, you may not always want to include them in your results or analyses. This filter allows you to include or exclude any works that came from MAG and only MAG. * Get all MAG-only works: [`https://api.openalex.org/works?filter=mag_only:true`](https://api.openalex.org/works?filter=mag_only:true) #### [](https://docs.openalex.org/api-entities/works/filter-works#primary_location.source.has_issn) `primary_location.source.has_issn` Value: a Boolean (`true` or `false`) Returns: works where the [`primary_location`](https://docs.openalex.org/api-entities/works/work-object#primary_location) has at least one ISSN assigned. * Get the works that have an ISSN within the primary location: [`https://api.openalex.org/works?filter=primary_location.source.has_issn:true`](https://api.openalex.org/works?filter=primary_location.source.has_issn:true) #### [](https://docs.openalex.org/api-entities/works/filter-works#primary_location.source.publisher_lineage) `primary_location.source.publisher_lineage` Value: the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for a [`Publisher`](https://docs.openalex.org/api-entities/publishers) Returns: works where the given publisher ID is in [`primary_location.source.host_organization_lineage`](https://docs.openalex.org/api-entities/sources/source-object#host_organization_lineage) * Get the works that have `https://openalex.org/P4310320547` in their `publisher_lineage`: [`https://api.openalex.org/works?filter=primary_location.source.publisher_lineage:https://openalex.org/P4310320547`](https://api.openalex.org/works?filter=primary_location.source.publisher_lineage:https://openalex.org/P4310320547) #### [](https://docs.openalex.org/api-entities/works/filter-works#raw_affiliation_strings.search) `raw_affiliation_strings.search` This filter used to be named `raw_affiliation_string.search`, but it is now `raw_affiliation_strings.search` (i.e., plural, with an 's'). Value: a search string Returns: works that have at least one [`raw_affiliation_strings`](https://docs.openalex.org/api-entities/works/work-object/authorship-object#raw_affiliation_strings) which includes the given string. See the [search page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) for details on the search algorithm used. * Get works with the words _Department of Political Science, University of Amsterdam_ somewhere in at least one author's `raw_affiliation_strings`: [`https://api.openalex.org/works?filter=raw_affiliation_strings.search:department%20of%20political%20science%20university%20of%amsterdam`](https://api.openalex.org/works?filter=raw_affiliation_strings.search:department%20of%20political%20science%20university%20of%20amsterdam) #### [](https://docs.openalex.org/api-entities/works/filter-works#related_to) `related_to` Value: the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for a given work Returns: works found in the given work's [`related_works`](https://docs.openalex.org/api-entities/works/work-object#related_works) section. * Get works related to [https://openalex.org/W2486144666](https://openalex.org/W2486144666) : [`https://api.openalex.org/works?filter=related_to:W2486144666`](https://api.openalex.org/works?filter=related_to:W2486144666) #### [](https://docs.openalex.org/api-entities/works/filter-works#repository) `repository` Value: the [OpenAlex ID](https://docs.openalex.org/how-to-use-the-api/get-single-entities#the-openalex-id) for a given [source](https://docs.openalex.org/api-entities/sources/source-object) , where the source is [`type: repository`](https://docs.openalex.org/api-entities/sources/source-object#type) Returns: works where the chosen [source ID](https://docs.openalex.org/api-entities/sources/source-object#id) exists within the [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) . You can use this to find works where authors are associated with your university, but the work is not part of the university's repository. 👏 * Get works that are available in the University of Michigan Deep Blue repository (OpenAlex ID: `https://openalex.org/S4306400393`) [`https://api.openalex.org/works?filter=repository:S4306400393`](https://api.openalex.org/works?filter=repository:S4306400393) * Get works where at least one author is associated with the University of Michigan, but the works are not found in the University of Michigan Deep Blue repository [`https://api.openalex.org/works?filter=institutions.id:I27837315,repository:!S4306400393`](https://api.openalex.org/works?filter=institutions.id:I27837315,repository:!S4306400393) You can also use this as a `group_by` to learn things about repositories: * Learn which repositories have the most open access works [`https://api.openalex.org/works?filter=is_oa:true&group_by=repository`](https://api.openalex.org/works?filter=is_oa:true&group_by=repository) #### [](https://docs.openalex.org/api-entities/works/filter-works#title_and_abstract.search) `title_and_abstract.search` Text search across titles and abstracts for works Value: a search string Returns: works whose [`display_name`](https://docs.openalex.org/api-entities/works/work-object#display_name) (title) or abstract includes the given string; see the [search page](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/search-entities) for details. * Get works with title or abstract mentioning "gum disease": [`https://api.openalex.org/works?filter=title_and_abstract.search:gum%20disease`](https://api.openalex.org/works?filter=title_and_abstract.search:gum%20disease) #### [](https://docs.openalex.org/api-entities/works/filter-works#to_created_date) `to_created_date` Value: a date, formatted as `yyyy-mm-dd` Returns: works with [`created_date`](https://docs.openalex.org/api-entities/works/work-object#created_date) less than or equal to the given date. This field requires an [OpenAlex Premium subscription to access. Click here to learn more.](https://openalex.org/pricing) * Get works created on or _after_ January 12th, 2023 (does not work without valid API key): [`https://api.openalex.org/works?filter=to_created_date:2024-01-12&api_key=myapikey`](https://api.openalex.org/works?filter=to_created_date:2024-01-12&api_key=myapikey) #### [](https://docs.openalex.org/api-entities/works/filter-works#to_publication_date) `to_publication_date` Value: a date, formatted as `yyyy-mm-dd` Returns: works with [`publication_date`](https://docs.openalex.org/api-entities/works/work-object#publication_date) less than or equal to the given date. * Get works published on or _before_ March 14th, 2001: [`https://api.openalex.org/works?filter=to_publication_date:2001-03-14`](https://api.openalex.org/works?filter=to_publication_date:2001-03-14) #### [](https://docs.openalex.org/api-entities/works/filter-works#to_updated_date) `to_updated_date` Value: a date, formatted as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date or date-time string (for example: "2020-05-17", "2020-05-17T15:30", or "2020-01-02T00:22:35.180390"). Returns: works with [`updated_date`](https://docs.openalex.org/api-entities/works/work-object#updated_date) less than or equal to the given date. This field requires an [OpenAlex Premium subscription to access. Click here to learn more.](https://openalex.org/pricing) * Get works updated before or on January 12th, 2023 (does not work without valid API key): [`https://api.openalex.org/works?filter=to_updated_date:2023-01-12&api_key=myapikey`](https://api.openalex.org/works?filter=to_updated_date:2023-01-12&api_key=myapikey) #### [](https://docs.openalex.org/api-entities/works/filter-works#version) `version` Value: a String with value `publishedVersion`, `submittedVersion`, `acceptedVersion`, or `null` Returns: works where the chosen version exists within the [`locations`](https://docs.openalex.org/api-entities/works/work-object#locations) . If `null`, it returns works where no version is found in any of the locations. * Get works where a published version is available in at least one of the locations: [`https://api.openalex.org/works?filter=version:publishedVersion`](https://api.openalex.org/works?filter=version:publishedVersion) [PreviousGet lists of works](https://docs.openalex.org/api-entities/works/get-lists-of-works) [NextSearch works](https://docs.openalex.org/api-entities/works/search-works) Last updated 22 days ago * [/works attribute filters](https://docs.openalex.org/api-entities/works/filter-works#works-attribute-filters) * [/works convenience filters](https://docs.openalex.org/api-entities/works/filter-works#works-convenience-filters) --- # Email Protection | Cloudflare Please enable cookies. Email Protection ================ You are unable to access this email address docs.openalex.org ------------------------------------------------------------- The website from which you got to this page is protected by Cloudflare. Email addresses on that page have been hidden in order to keep them from being accessed by malicious bots. **You must enable Javascript in your browser in order to decode the e-mail address**. If you have a website and are interested in protecting it in a similar way, you can [sign up for Cloudflare](https://www.cloudflare.com/sign-up?utm_source=email_protection) . * [How does Cloudflare protect email addresses on website from spammers?](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/) * [Can I sign up for Cloudflare?](https://developers.cloudflare.com/fundamentals/setup/account/create-account/) Cloudflare Ray ID: **9b964326bdf6c960** • Your IP: Click to reveal 54.237.218.47 • Performance & security by [Cloudflare](https://www.cloudflare.com/5xx-error-landing) ---