Advanced search

🚧

New record status values, filters and API behaviors

Beginning 1 Dec 2022, some ROR records contain new values "inactive" and "withdrawn" in the status and new values "Predecessor" and "Successor" in relationships.type. APIs now return records with active status only by default. Records with all statuses can be returned using query parameter ?all_status. See the 2022-12-01 release notes for details about this change.

Advanced search functionality allows searching all ROR record fields using the URL query parameter query.advanced. Complex queries using field names, wildcards, boolean operators, etc can be constructed using Elastic Search query string syntax.

Example queries

Search all fields

To search all ROR record fields, use ?query.advanced=[query]. Queries should be formatted using Elastic Search query string syntax.

• URL-encode query terms
• Escape Elastic Search reserved characters

curl 'https://api.ror.org/organizations?query.advanced=Harvard%20University'

🚧

Querying all fields with ?query.advanced=[query] may produce more results than desired. Consider searching one or more specific fields instead, e.g., ?query.advanced=[fieldname:query], as in the example below.

Search a single field

Elastic Search field name syntax fieldname:query can be used to search a single field. When using this syntax, field name must match a field name in the list of available fields exactly (ex: addresses.geonames_city.city:Melbourne not addresses:Melbourne). To search child fields of a parent field see Search all subfields of a parent field.

curl 'https://api.ror.org/organizations?query.advanced=name:Harvard%20University'

Search multiple fields

Combine multiple fields to form complex queries Elastic Search boolean operator syntax (AND, OR, NOT). Note that operators must be surrounded by URL-encoded spaces.

curl 'https://api.ror.org/organizations?query.advanced=name:Cornell+AND+addresses.geonames_city.city:Ithaca'

Search all subfields of a parent field

Elastic Search field name syntax fieldname.\*:query can be used to search all subfields of a parent field. Note that \ characters must be URL-encoded.

curl 'https://api.ror.org/organizations?query.advanced=addresses.%5c*:Melbourne'

Find a records with a non-null value in a field

Elastic Search field name syntax _exists_:[fieldname] can be used to return records that have any non-null value in that field.

🚧

Null vs empty string

Most ROR record fields that have no value are set to null. An exception is wikipedia_url. Empty wikipedia_url values were set to empty strings "" in inherited GRID records.

For some other fields, like addresses.line, most empty values were set to null, but a small number of records inherited from GRID have empty strings.

We plan to change empty strings to null in a future data release, however, currently _exists_:[fieldname] may include results with empty strings for some fields.

curl 'https://api.ror.org/organizations?query.advanced=_exists_:external_ids.ISNI.all'

Paging

As with all ROR API responses, advanced query results are paginated. By default, the first 20 results are returned, and more results can be retrieved with additional requests. See ROR API > Paging for details on retrieving paginated results.

Filtering

As with all ROR API responses, advanced query results can be filtered by type, country code, country name or status using the filter parameter. See ROR API > Filtering for details on filtering.

Record status

As of 1 Dec, 2022 API search/list responses return only records with a status of active by default (see release notes). Add the query parameter ?all_status to return records with all statuses (active, inactive, withdrawn) or filter by status to return records with specific status values. See ROR API > Record status for more information.

Errors & troubleshooting

Incorrect field names

The following cases will cause a field name validation error:

• Performing fielded searches that contain field names not listed in the table below
• Searching a parent field name without using a wildcard operator (ex: addresses:Melbourne rather than addresses.%5c*:Melbourne

For example, a query with an incorrect field name will return the following error:

curl 'https://api.ror.org/organizations?query.advanced=address.city:Melbourne'
{"errors":["string 'address.city' contains an illegal field name"]}

Multiple query parameters

Use either query or query.advanced parameter - not both. If both are used, the following error will be returned:

curl 'https://api.ror.org/organizations?query.advanced=name:Cornell&query=Ithaca'
{"errors":["query and query.advanced parameters cannot be combined. please use either query OR query.advanced"]}

Unescaped reserved characters

Elasticsearch reserved characters + - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ / used within your search terms must be escaped with a URL-encoded \ character, %5c. If these characters are not escaped, the following issues may occur:

• Illegal field name error, due to unescaped : character, which is interpreted as a field name
• 500 error, ex due to unterminated/unescaped special characters
• Unexpected/non-relevant results, due to special characters being interpreted as query operators rather than as part of your search terms

For additional details, see ROR API > Special characters

Search strings with spaces

Elasticsearch query string syntax will treat words separated by a space as separate parts of a query. It is therefore advisable to surround multi-word search terms of the ROR API with URL-encoded quotation marks.

• Search terms without quotation marks - 0 results: https://api.ror.org/organizations?query.advanced=addresses.city:New%20York

• Search term with quotation marks - 1332 results: https://api.ror.org/organizations?query.advanced=addresses.city:%22New%20York%22

Available fields

How is this different from the existing ?query search?

?query.advanced searches Elastic Search documents that contain all fields/subfields in all ROR records. Field names and hierarchy are preserved.

?query searches abbreviated Elastic Search documents (called "names_ids") that combine all the values from each ROR record's name, aliases, labels, acronyms, id, and external_ids fields. For labels and external IDs, only the values (not the language code or type are included). Field names are removed, and each value is simply categorized as a "name" or "id".

Example names_ids document (truncated)

"names_ids" : [
            {
              "name" : "University of Wisconsin–Madison"
            },
            {
              "name" : "Université du Wisconsin à Madison"
            },
            {
              "name" : "Universidad de Wisconsin-Madison"
            },
            {
              "name" : "UW–Madison"
            },
            {
              "name" : "UW"
            },
            {
              "id" : "https://ror.org/01y2jtd41"
            },
            {
              "id" : "ror.org/01y2jtd41"
            },
            {
              "id" : "01y2jtd41"
            },
...