Skip to content

Latest commit

 

History

History
194 lines (128 loc) · 6.46 KB

README.md

File metadata and controls

194 lines (128 loc) · 6.46 KB
description
Short words or phrases assigned to works using AI

🗝️ Keywords

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.

Keyword object

These are the fields in a keyword object. When you use the API to get a single keyword or lists of keywords, this is what's returned.

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.

cited_by_count: 4347000

created_date

String: The date this Keyword object was created in the OpenAlex dataset, expressed as an ISO 8601 date string.

created_date: "2024-04-10"

display_name

String: The English-language label of the keyword.

display_name: "Cardiac Imaging"

id

String: The OpenAlex ID for this keyword.

id: "https://openalex.org/keywords/cardiac-imaging"

updated_date

String: The last time anything in this keyword object changed, expressed as an ISO 8601 date string. This date is updated for any change at all, including increases in various counts.

updated_date: "2024-05-09T05:00:03.798420"

works_count

Integer: The number of works tagged with this keyword.

works_count: 21737

Get a single keyword

It's easy to get a keyword from the API with: /keyword/<entity_id>. Here's an example:

That will return a Keyword object, describing everything OpenAlex knows about the keyword with that ID:

{
    "id": "https://openalex.org/keywords/cardiac-imaging",
    "display_name": "Cardiac Imaging",
    // other fields removed for brevity
}

{% hint style="info" %} You can make up to 50 of these queries at once by requesting a list of entities and filtering on IDs using OR syntax. {% endhint %}

Select fields

You can use select to limit the fields that are returned in a keyword object. More details are here.

Get a list of keywords

You can get lists of keywords:

Which returns a response like this:

{
    "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": []
}

Filter keywords

You can filter keywords with the filter parameter:

{% hint style="info" %} It's best to read about filters before trying these out. It will show you how to combine filters and build an AND, OR, or negation query {% endhint %}

/keywords attribute filters

You can filter using these attributes of the Keyword object:

/keywords convenience filters

These filters aren't attributes of the Keyword object, but they're included to address some common use cases:

default.search

Value: a search string

This works the same as using the search parameter for Keywords.

display_name.search

Value: a search string

Returns: keywords with a display_name containing the given string.

Search keywords

You can search for keywords using the search query parameter, which searches the display_name fileds. For example:

{% hint style="info" %} You can read more about search here. It will show you how relevance score is calculated, how words are stemmed to improve search results, and how to do complex boolean searches. {% endhint %}

Group keywords

You can group keywords with the group_by parameter:

Or you can group using one the attributes below.

{% hint style="info" %} It's best to read about group by before trying these out. It will show you how results are formatted, the number of results returned, and how to sort results. {% endhint %}

Keywords group_by attributes