OpenAlex technical documentation
  • Overview
  • Quickstart tutorial
  • API Entities
    • Entities overview
    • 📄Works
      • Work object
        • Authorship object
        • Location object
      • Get a single work
      • Get lists of works
      • Filter works
      • Search works
      • Group works
      • Get N-grams
    • 👩Authors
      • Author object
      • Get a single author
      • Get lists of authors
      • Filter authors
      • Search authors
      • Group authors
      • Limitations
      • Author disambiguation
    • 📚Sources
      • Source object
      • Get a single source
      • Get lists of sources
      • Filter sources
      • Search sources
      • Group sources
    • 🏫Institutions
      • Institution object
      • Get a single institution
      • Get lists of institutions
      • Filter institutions
      • Search institutions
      • Group institutions
    • 💡Topics
      • Topic object
      • Get a single topic
      • Get lists of topics
      • Filter topics
      • Search topics
      • Group topics
    • 🗝️Keywords
    • 🏢Publishers
      • Publisher object
      • Get a single publisher
      • Get lists of publishers
      • Filter publishers
      • Search publishers
      • Group publishers
    • 💰Funders
      • Funder object
      • Get a single funder
      • Get lists of funders
      • Filter funders
      • Search funders
      • Group funders
    • 🌎Geo
      • Continents
      • Regions
    • Concepts
      • Concept object
      • Get a single concept
      • Get lists of concepts
      • Filter concepts
      • Search concepts
      • Group concepts
    • Aboutness endpoint (/text)
  • How to use the API
    • API Overview
    • Get single entities
      • Random result
      • Select fields
    • Get lists of entities
      • Paging
      • Filter entity lists
      • Search entities
      • Sort entity lists
      • Select fields
      • Sample entity lists
      • Autocomplete entities
    • Get groups of entities
    • Rate limits and authentication
  • Download all data
    • OpenAlex snapshot
    • Snapshot data format
    • Download to your machine
    • Upload to your database
      • Load to a data warehouse
      • Load to a relational database
        • Postgres schema diagram
  • Additional Help
    • Tutorials
    • Report bugs
    • FAQ
Powered by GitBook
On this page
  • associated_institutions
  • cited_by_count
  • country_code
  • counts_by_year
  • created_date
  • display_name
  • display_name_acronyms
  • display_name_alternatives
  • geo
  • homepage_url
  • id
  • ids
  • image_thumbnail_url
  • is_super_system
  • image_url
  • international
  • lineage
  • repositories
  • roles
  • ror
  • summary_stats
  • type
  • updated_date
  • works_api_url
  • works_count
  • x_concepts
  • The DehydratedInstitution object
Export as PDF
  1. API Entities
  2. Institutions

Institution object

PreviousInstitutionsNextGet a single institution

Last updated 10 months ago

These are the fields in an institution object. When you use the API to get a or , this is what's returned.

associated_institutions

List: Institutions related to this one. Each associated institution is represented as a 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 .

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
]

cited_by_count

cited_by_count: 21199844 

country_code

country_code: "US"

counts_by_year

Years with zero citations and zero works have been removed so you will need to add those in if you need them.

counts_by_year: [
    {
        year: 2022,
        works_count: 133,
        cited_by_count: 32731
    },
    {
        year: 2021,
        works_count: 12565,
        cited_by_count: 2180827
    },
    
    // and so forth
]

created_date

created_date: "2017-08-08"

display_name

String: The primary name of the institution.

display_name: "University of North Carolina at Chapel Hill"

display_name_acronyms

display_name_acronyms:["UNC"]

display_name_alternatives

List: Other names people may use for this institution.

display_name_alternatives: [
    "UNC-Chapel Hill"
]

geo

Object: A bunch of stuff we know about the location of this institution:

  • city (String): The city where this institution lives.

  • region (String): The sub-national region (state, province) where this institution lives.

  • country (String): The country where this institution lives.

  • latitude (Float): Does what it says.

  • longitude (Float): Does what it says.

geo: {
    city: "Chapel Hill",
    geonames_city_id: "4460162",
    region: "North Carolina",
    country_code: "US",
    country: "United States",
    latitude: 35.9083,
    longitude: -79.0492
}

homepage_url

String: The URL for institution's primary homepage.

homepage_url: "http://www.unc.edu/"

id

id: "https://openalex.org/I114027177"

ids

Object: All the external identifiers that we know about for this institution. IDs are expressed as URIs whenever possible. Possible ID types:

  • wikipedia (String: this institution's Wikipedia page URL)

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.

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
}  

image_thumbnail_url

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"

is_super_system

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.

image_url: "https://upload.wikimedia.org/wikipedia/en/5/5c/University_of_North_Carolina_at_Chapel_Hill_seal.svg"

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)

    • value (String): display_name in the given language

international: {
    display_name: {
        "ar": "جامعة نورث كارولينا في تشابل هيل",
        "en": "University of North Carolina at Chapel Hill",
        "es": "Universidad de Carolina del Norte en Chapel Hill",
        "zh-cn": "北卡罗来纳大学教堂山分校",
        ...
    }
}

lineage

id: "https://openalex.org/I170203145",
...
lineage: [
    "https://openalex.org/I170203145",
    "https://openalex.org/I90344618"
]

repositories

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
]

roles

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.

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,
    }
]

ror

ror: "https://ror.org/0130frc33"

summary_stats

Object: Citation metrics 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.

summary_stats: {
    2yr_mean_citedness: 5.065784263815827,
    h_index: 985,
    i10_index: 176682
}

type

Possible values are: Education, Healthcare, Company, Archive, Nonprofit, Government, Facility, and Other.

type: "education"

updated_date

updated_date: "2022-01-02T00:27:23.088909"

works_api_url

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.

works_api_url: "https://api.openalex.org/works?filter=institutions.id:I114027177"

works_count

works_count: 202704    

x_concepts

  • score (Float): The strength of association between this institution and the listed concept, from 0-100.

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
]

The DehydratedInstitution object

Integer: The total number that cite a work created by an author affiliated with this institution. Or less formally: the number of citations this institution has collected.

String: The country where this institution is located, represented as an .

List: and 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.

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

List: Acronyms or initialisms that people sometimes use instead of the full .

geonames_city_id (String): The city where this institution lives, as a ID.

country_code (String): The country where this institution lives, represented as an .

String: The for this institution.

grid (String: this institution's )

mag (Integer: this institution's ID)

openalex (String: this institution's . Same as )

ror (String: this institution's ROR ID. Same as )

wikidata (String: this institution's )

String: Same as , but it's a smaller image.

Boolean: True if this institution is a "super system". This includes large university systems such as the University of California System (), 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' , 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 .

key (String): language code in format. Full list of languages is .

List: 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 , specifically the Parent/Child relationships.

Super systems are excluded from the lineage. See above.

List: Repositories ( with type: repository) that have this institution as their

List: List of role objects, which include the role (one of institution, funder, or publisher), the id (), and the works_count.

The roles list of an entity (, , or ) 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.

String: The ID for this institution. This is the for institutions.

The ROR (Research Organization Registry) identifier is a globally unique ID for research organization. , which is no longer being updated.

2yr_mean_citedness Float: The 2-year mean citedness for this source. Also known as . 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 for this institution.

i10_index Integer: The for this institution.

String: The institution's primary type, using the .

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

String: A URL that will get you a list of all the affiliated with this institution.

Integer: The number of created by authors affiliated with this institution. Or less formally: the number of works coming out of this institution.

x_concepts will be deprecated and removed soon. We will be replacing this functionality with instead.

List: The most frequently applied to works affiliated with this institution. Each is represented as a object, with one additional attribute:

The DehydratedInstitution is a stripped-down object, with most of its properties removed to save weight. Its only remaining properties are:

🏫
Works
ISO two-letter country code
ISO 8601
GeoNames database
ISO two-letter country code
GRID
ID
Microsoft Academic Graph
Wikidata ID
https://openalex.org/I2803209242
this file
wikidata language code
here
ROR's relationships
Funder
Publisher
Institution
ROR is the successor to GRiD
impact factor
h-index
i-10 index
ROR "type" controlled vocabulary
ISO 8601
Works
Works
Topics
Institution
single institution
lists of institutions
ROR's relationships
dehydrated Institution
works_count
cited_by_count
display_name
Institution.ror
image_url
lineage
is_super_system
country_code
display_name
id
lineage
ror
type
Sources
ROR
Concepts
Institution.id
OpenAlex ID
OpenAlex ID
OpenAlex IDs
OpenAlex ID
Canonical External ID
host_organization
dehydrated Concept