Source lists

Eg:source-lists/doyensCount:22Links:sources, works

A source list is an externally maintained list of journals that a source can appear on: the Directory of Open Access Journals, the CWTS Core sources list, a national list of recommended health journals. Source lists are a vocabulary: consistent handles on lists that exist outside OpenAlex, maintained by someone else. Each source carries a listed_in array of the lists it is on, and the dehydrated source inside every work location carries the same array, so works can be filtered by the lists their journal is on. A source list’s OpenAlex ID looks like https://openalex.org/source-lists/doyens; fetch one at api.openalex.org/source-lists/doyens.

Membership is all OpenAlex records. A list’s page says who maintains it, what it covers and which edition is loaded; it never says the list is right, and OpenAlex does not endorse any list. See Allow lists for why we prefer this over deny lists.

About

OpenAlex prefers allow lists to deny lists: they are transparent, easy to maintain and a sound basis for retrieval. The oldest ones arrived as booleans (is_in_doaj, is_core); listed_in and this entity are the general form, and the booleans are kept for compatibility.

A source list is not an index. An index records which external registries list a given work (indexed_in); a source list records which lists a journal is on. DOAJ appears in both, answering different questions: is this article in DOAJ’s index, versus is this journal a DOAJ member.

Lists are matched to sources by ISSN, and only a list’s current members count: a journal its maintainer has withdrawn is not listed_in. Each list is loaded from the maintainer’s published file, so membership is as current as the loaded edition (list_version). Spotted a newer edition, or know an open, ISSN-keyed list we should add? Tell us.

Values

Where a maintainer ranks journals in levels (the Norwegian Register, JUFO, JPPS, KI-JL, ABDC), each level is its own list, named with the maintainer’s own label: norway-2, jufo-3, abdc-a-star. Those frameworks exist to get away from the in-or-out binary, so OpenAlex keeps the levels rather than flattening them. A journal is on exactly one level of a given register; to get “any level”, filter on all of them (listed_in:jufo-1|jufo-2|jufo-3). In the numbered registers a higher level is the more selective tier; ABDC runs the other way, with A* at the top and C at the bottom. States that aren’t a level (not yet evaluated, pending, level 0) are not lists.

The live list is at api.openalex.org/source-lists.

Attributes

The top-level fields on a source list object. Attributes shared with other entities (id, display_name, works_count, cited_by_count, created_date, updated_date) are documented once on Common attributes.

id

String. The OpenAlex ID for this list, e.g. https://openalex.org/source-lists/doyens. The last segment is the value that appears in listed_in.

display_name

String. The list’s name as its maintainer publishes it, e.g. Liste de revues recommandables (CDD / CNU Santé).

description

String. What the list covers, in a sentence.

maintainer

String. The organisation that maintains the list.

url

String. Where the maintainer publishes the list.

list_version

String. The edition currently loaded, as a date (YYYY-MM-DD); null for lists derived continuously from another feed (DOAJ, CWTS Core).

sources_count

Integer. How many OpenAlex sources are on this list.

works_count

Integer. How many works have their primary location in a source on this list. See Common attributes.

cited_by_count

Integer. Total citations across those works. See Common attributes.

sources_api_url

String. A ready-made Sources API URL for every source on this list (filter=listed_in:<ID>).

works_api_url

String. A ready-made Works API URL for every work whose primary location is on this list (filter=primary_location.source.listed_in:<ID>).

created_date

String. When the list was added to OpenAlex (YYYY-MM-DD). See Common attributes.

updated_date

String. When the list record last changed. See Common attributes.

In the API

The Source lists endpoint is at api.openalex.org/source-lists. Fetch one by ID, /source-lists/doyens, or list them all.

Source lists are most useful as a filter. On sources, filter=listed_in:doyens returns the journals on the list and group_by=listed_in splits a result set across lists. On works, filter=primary_location.source.listed_in:doyens returns works published in those journals; locations.source.listed_in and best_oa_location.source.listed_in do the same for any location and the best OA location. See Filtering for the syntax and the endpoints index for every endpoint.

On openalex.org, the same thing is the listed in filter on sources (example) and source listed in on works (example).