View Source ROR.Client (ROR v0.1.0)

Low-level functions for using the ROR REST API, returning maps parsed from the API's JSON responses.

It's normally better to use the ROR module, unless you want to use the decoded JSON responses from the API, or pass parameters and headers directly.

Parameters are passed as a map or keyword list of strings. They do not need to be URL-encoded (ROR will do that) but you must manually escape any ElasticSearch symbols. IDs are normalized. Things like changing the API base URL must be done by passing options to the Req HTTP library using the :http option.

Summary

Functions

affiliation!(value, opts \\ [])

Attempts to find organizations that match the provided string, with levels of confidence that an organization has been identified. Returns a map of match results, each with an organization map.

get!(id, opts \\ [])

Retrieve a single organization record as a map using its ROR ID.

list!(opts \\ [])

Returns a map that contains organization records.

query!(value, opts \\ [])

Searches names and external_ids in the ROR database and returns a map that has a list of organization records.

query_advanced!(value, opts \\ [])

Searches all fields in the ROR database if given a simple string, or allows use of ElasticSearch-style search queries. Returns a map that has a list of organization records (also as maps).

Functions

affiliation!(value, opts \\ [])

@spec affiliation!(value :: binary(), opts :: keyword()) :: map()

Attempts to find organizations that match the provided string, with levels of confidence that an organization has been identified. Returns a map of match results, each with an organization map.

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

  • params: A map or keyword list of HTTP params that is passed to Req and merged with defaults (optional)
  • headers: A map or keyword list of HTTP headers that is passed to Req and merged with defaults (optional)
  • http: A map or keyword list of Req options that is passed to Req and merged with defaults (optional)

Example 

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

get!(id, opts \\ [])

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

Retrieve a single organization record as a map 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 data cannot be returned

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

Options

  • params: A map or keyword list of HTTP params that is passed to Req and merged with defaults (optional)
  • headers: A map or keyword list of HTTP headers that is passed to Req and merged with defaults (optional)
  • http: A map or keyword list of Req options that is passed to Req and merged with defaults (optional)

Example 

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

list!(opts \\ [])

@spec list!(opts :: keyword()) :: map()

Returns a map that contains organization records.

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

  • params: A map or keyword list of HTTP params that is passed to Req and merged with defaults (optional)
  • headers: A map or keyword list of HTTP headers that is passed to Req and merged with defaults (optional)
  • http: A map or keyword list of Req options that is passed to Req and merged with defaults (optional)

Example 

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

query!(value, opts \\ [])

@spec query!(value :: binary(), opts :: keyword()) :: map()

Searches names and external_ids in the ROR database and returns a map that has a list of organization records.

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

  • params: A map or keyword list of HTTP params that is passed to Req and merged with defaults (optional)
  • headers: A map or keyword list of HTTP headers that is passed to Req and merged with defaults (optional)
  • http: A map or keyword list of Req options that is passed to Req and merged with defaults (optional)

Example 

iex> ROR.Client.query!("'New York'", params: [page: "3"])

query_advanced!(value, opts \\ [])

@spec query_advanced!(value :: binary(), opts :: keyword()) :: map()

Searches all fields in the ROR database if given a simple string, or allows use of ElasticSearch-style search queries. Returns a map that has a list of organization records (also as maps).

This API call is slower and more resource-intensive than query/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

  • params: A map or keyword list of HTTP params that is passed to Req and merged with defaults (optional)
  • headers: A map or keyword list of HTTP headers that is passed to Req and merged with defaults (optional)
  • http: A map or keyword list of Req options that is passed to Req and merged with defaults (optional)

Example 

iex> ROR.Client.query_advanced!("'Harvard University'", params: [page: "1"])
...> 
...> ROR.Client.query_advanced!(
...>   "names.value:Cornell AND locations.geonames_details.name:Ithaca"
...> )