View Source ROR (ROR v0.1.0)

ROR is an unofficial client for the Research Organization Registry (ROR) API for Elixir. This top level ROR module contains functions for retrieving data via the API.

The Research Organization Registry (ROR) includes IDs and metadata for more than 110,000 organizations and counting. Registry data is CC0 and openly available via a search interface, REST API, and data dump. Registry updates are curated through a community process and released at least once a month

Please read ROR's terms of use and do not put excessive load on their API service.

Features

  • Lookup individual ROR records by ID
  • Search and Quick Search based on names or record attributes
  • Paging and filters for queries and lists
  • Match text to records, possibly identifying an organisation from existing data
  • Records are returned as typed structs (slightly different to the ROR JSON responses, but containing all the information)
  • Client ID authentication is supported and optional
  • API service heartbeat checks
  • (This is an early version and only contains the basics so far)

You may not need to use the other ROR modules directly at all, but here are a few that might be handy:

  • ROR.Client presents a lower-level way to retrieve data, and returns maps based on the literal ROR JSON responses.
  • ROR.Organization contains a struct and utilities for the main ROR organization record
  • ROR.Results is an enumerable struct that contains both Organizations and metadata
  • ROR.Matches is another enumerable struct, which contains results from affiliation searches

Defining Filters

Filters are used to fine-tune results before they are returned.

Results can be filtered by record status, organization type, ISO 3166 country code, country name, continent code, and continent name.

In the ROR module they are defined directly using either a keyword list

iex> ROR.list!(filter: [type: :government])

or by creating a ROR.Filter struct, and passing that

iex> my_filter = ROR.Filter.new(status: :inactive, types: :facility)
...> ROR.list!(filter: my_filter)

You can read more about filters in the official ROR docs

Authentication

The ROR API does not require authentication, but it can be used to permit heavier usage. You must register on the ROR website for a key/token, and then include that in calls using the :client_id option like this:

iex> ROR.get!("https://ror.org/04h699437", client_id: "client ID goes here")

Paging

API calls that return multiple results will limit them to pages of 20 organizations at a time, and default to page 1.

You can specify pages using the :page option.

iex> ROR.list!(page: 20)

You can read more about paging in the official ROR docs

Results and Matches

Results are returned as ROR.Results and ROR.Matches structs which contain a list of ROR.Organization structs and some metadata. They are enumerable, so you can use Enum functions on them directly.

So, iterating through the items in the Results struct and iterating directly are equivalent

iex> results = ROR.list!()
...> # this
...> Enum.map(results.items, fn o -> o.id end)
...> # can also be done like this
...> Enum.map(results, fn o -> o.id end)

Stringifying ROR structs

Many structs used by the ROR library can be converted to strings, and converted automatically if interpolated inside other strings. This can be useful when logging and debugging.

Information will be lost, and the process is one-way - you cannot convert them back to structs from strings.

iex> org = ROR.get!("https://ror.org/04h699437")
...> to_string(org)
"https://ror.org/04h699437"
iex> org = ROR.get!("https://ror.org/04h699437")
...> to_string(org.admin)
"2018-11-14, 2024-12-11"

Examples

Retrieving data about an organization using its ROR ID 

iex> org = ROR.get!("https://ror.org/04h699437")
...> org.domains
["le.ac.uk"]

List ROR records, specifying a page and a filter 

iex> ROR.list!(page: 15, filter: [type: :government])
...> |> Enum.map(fn org -> org.id end)
...> |> Enum.count()
20
iex> a =
...>   ROR.quick_search!("University of Manchester")
...>   |> Enum.take(1)
...>   |> List.first()
...> 
...> a.established
1824

An affiliation search for strong match or nil, also showing off the string conversion feature 

iex> org = ROR.chosen_organization!("CERN")
...> Enum.map(org.names, &to_string/1)
[
  "CERN",
  "European Organization for Nuclear Research",
  "Europäische Organisation für Kernforschung",
  "Organisation européenne pour la recherche nucléaire"
]

Summary

Functions

api_versions()

Returns a list of supported API versions.

chosen_organization!(search, opts \\ [])

Attempts to identify one organization that has been chosen as a close match for the string, or returns nil if there is any ambiguity.

exists?(id, opts \\ [])

Check if a single, specified record is available via the API, returning true or false.

get!(id, opts \\ [])

Retrieve a single Organization record using its ROR ID.

heartbeat?(opts \\ [])

Returns true if the API is available

identify!(search, opts \\ [])

Attempts to find organizations that match the provided string, with levels of confidence that an organization has been identified. Returns a Matches struct, which contains a list of Match records, each with an Organization.

list!(opts \\ [])

Returns a Results struct that contains Organization structs.

quick_search!(search, opts \\ [])

Searches names and external_ids in the ROR database and returns a Results struct that has a list of Organization structs.

search!(search, opts \\ [])

Searches all fields in the ROR database if given a simple string, or allows use of ElasticSearch-style search queries. Returns a Results struct that has a list of Organization structs.

Functions

api_versions()

@spec api_versions() :: [binary()]

Returns a list of supported API versions.

Example 

iex> ROR.api_versions()
["v2.1"]

chosen_organization!(search, opts \\ [])

@spec chosen_organization!(value :: binary(), opts :: keyword()) ::
  ROR.Organization.t() | nil

Attempts to identify one organization that has been chosen as a close match for the string, or returns nil if there is any ambiguity.

Results cannot be paged or filtered.

An exception will be raised if matches cannot be returned.

Options

  • api_url: The base URL (optional)
  • client_id: ROR authentication token (optional)

Example 

iex> ROR.chosen_organization!(
...>   "Department of Civil and Industrial Engineering, University of Pisa, Largo Lucio Lazzarino 2, Pisa 56126, Italy"
...> )

exists?(id, opts \\ [])

@spec exists?(id :: binary(), opts :: keyword()) :: map()

Check if a single, specified record is available via the API, returning true or false.

The ID can be any valid format: https://ror.org/04h699437, ror.org/04h699437 or 04h699437

False will be returned if the ID is invalid, or the URL incorrect, or the record simply isn't available.

Options

  • api_url: The base URL (optional)
  • client_id: ROR authentication token (optional)

Example 

iex> ROR.exists?("https://ror.org/04h699437")
true

get!(id, opts \\ [])

@spec get!(id :: binary(), opts :: keyword()) :: map()

Retrieve a single Organization record using its ROR ID.

The ID can be any valid format: https://ror.org/04h699437, ror.org/04h699437 or 04h699437

An exception will be raised if an Organization cannot be returned

You can read more about getting a single record in the official ROR docs

Options

  • api_url: The base URL (optional)
  • client_id: ROR authentication token (optional)

Example 

iex> ROR.get!("https://ror.org/04h699437")

heartbeat?(opts \\ [])

@spec heartbeat?(opts :: keyword()) :: boolean()

Returns true if the API is available

## Options

  • api_url: The base URL (optional)

Example 

iex> ROR.heartbeat?()
true
iex> ROR.heartbeat?(api_url: "https://incorrect.example.com/organizations")
false

identify!(search, opts \\ [])

@spec identify!(value :: binary(), opts :: keyword()) :: ROR.Matches.t()

Attempts to find organizations that match the provided string, with levels of confidence that an organization has been identified. Returns a Matches struct, which contains a list of Match records, each with an Organization.

This API call is potentially useful for finding the correct ROR organization record for existing data, but must be used carefully.

Results cannot be paged or filtered.

An exception will be raised if matches cannot be returned.

You can read more about affiliation queries in the official ROR docs

Options

  • api_url: The base URL (optional)
  • client_id: ROR authentication token (optional)

Example 

iex> ROR.identify!(
...>   "Department of Civil and Industrial Engineering, University of Pisa, Largo Lucio Lazzarino 2, Pisa 56126, Italy"
...> )

list!(opts \\ [])

@spec list!(opts :: keyword()) :: ROR.Results.t()

Returns a Results struct that contains Organization structs.

An exception will be raised if a list of organizations data cannot be returned

You can read more about getting a list of records in the official ROR docs

Options

  • api_url: The base URL (optional)
  • client_id: ROR authentication token (optional)
  • page: a page number (optional)
  • filter: filter options, or a Filter Struct (optional)
  • all_status: set to true to return active, inactive and withdrawn organizations (optional)

Example 

iex> ROR.list!(page: 3, filter: [type: :government])

quick_search!(search, opts \\ [])

@spec quick_search!(value :: binary(), opts :: keyword()) :: ROR.Results.t()

Searches names and external_ids in the ROR database and returns a Results struct that has a list of Organization structs.

This style of search is relatively quick and simple, and suitable for things like auto-suggestion lookups.

An exception will be raised if results cannot be returned

You can read more about querying records in the official ROR docs

Options

  • api_url: The base URL (optional)
  • client_id: ROR authentication token (optional)
  • page: a page number (optional)
  • filter: filter options, or a Filter Struct (optional)
  • all_status: set to true to return active, inactive and withdrawn organizations (optional)

Example 

iex> ROR.quick_search!("'New York'", page: 1)

search!(search, opts \\ [])

@spec search!(value :: binary(), opts :: keyword()) :: ROR.Results.t()

Searches all fields in the ROR database if given a simple string, or allows use of ElasticSearch-style search queries. Returns a Results struct that has a list of Organization structs.

This API call is slower and more resource-intensive than quick_search/2 but allows more precision.

An exception will be raised if results cannot be returned.

You can read more about advanced queries in the official ROR docs

Options

  • api_url: The base URL (optional)
  • client_id: ROR authentication token (optional)
  • page: a page number (optional)
  • filter: filter options, or a Filter Struct (optional)
  • all_status: set to true to return active, inactive and withdrawn organizations (optional)

Example 

iex> ROR.search!("'Harvard University'", page: 1)
...> ROR.search!("names.value:Cornell AND locations.geonames_details.name:Ithaca")