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'

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 or country name using the filter parameter. See ROR API > Filtering for details on filtering.

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

Field name	Description	Notes
acronyms	Acronyms or initialisms for the organization name
addresses.city	City that the organization is located in	In new and recently updated records, this value is identical to `addresses.geonames_city.city`. In records inherited from GRID, this value may be different from `addresses.geonames_city.city` or missing.
addresses.country_geonames_id	Geonames ID for the country that the organization is located in
addresses.geonames_city.city	City that the organization is located in, from Geonames database	Derived from the Geonames record for the ID addresses.geonames_city.id
addresses.geonames_city.geonames_admin1.ascii_name	ASCII name for the primary administrative region (ex: US state) that the organization is located in, from Geonames database	Derived from the Geonames record for the ID addresses.geonames_city.id
addresses.geonames_city.geonames_admin1.code	Code for the primary administrative region (ex: US state) that the organization is located in, from Geonames database. Typically a FIPs or ISO code.	Derived from the Geonames record for the ID addresses.geonames_city.id
addresses.geonames_city.geonames_admin1.name	Name of the primary administrative region (ex: US state) that the organization is located in, from Geonames database. May contain non-ASCII characters.	Derived from the Geonames record for the ID addresses.geonames_city.id
addresses.geonames_city.geonames_admin2.ascii_name	ASCII name for the secondary administrative region (ex: US county) that the organization is located in, from Geonames database	Derived from the Geonames record for the ID addresses.geonames_city.id
addresses.geonames_city.geonames_admin2.code	Code for the secondary administrative region (ex: US county) that the organization is located in, from Geonames database	Derived from the Geonames record for the ID addresses.geonames_city.id
addresses.geonames_city.geonames_admin2.name	Name of the secondary administrative region (ex: US county) that the organization is located in, from Geonames database. May contain non-ASCII characters.	Derived from the Geonames record for the ID addresses.geonames_city.id
addresses.geonames_city.id	Geonames ID for the city that the organization is located in	A small number of organizations are not located in a city. In that case, the code for the nearest legal jurisdiction is used.
addresses.geonames_city.license.attribution	License attribution for Geonames data	Value in all records is `Data from geonames.org under a CC-BY 3.0 license`
addresses.geonames_city.license.license	License URL for Geonames data	Value in all records is `http://creativecommons.org/licenses/by/3.0`
addresses.geonames_city.nuts_level1.code	Code for the NUTS level 1 region that the organization is located in, from Geonames database	DEPRECATED. This field does not have a value in new and recently updated records, and values in existing records are not maintained.
addresses.geonames_city.nuts_level1.name	Name of the NUTS level 1 region that the organization is located in, from Geonames database	DEPRECATED. This field does not have a value in new and recently updated records, and values in existing records are not maintained.
addresses.geonames_city.nuts_level2.code	Code for the NUTS level 2 region that the organization is located in, from Geonames database	DEPRECATED. This field does not have a value in new and recently updated records, and values in existing records are not maintained.
addresses.geonames_city.nuts_level2.name	Name of the NUTS level 2 region that the organization is located in, from Geonames database	DEPRECATED. This field does not have a value in new and recently updated records, and values in existing records are not maintained.
addresses.geonames_city.nuts_level3.code	Code for the NUTS level 3 region that the organization is located in, from Geonames database	DEPRECATED. This field does not have a value in new and recently updated records, and values in existing records are not maintained.
addresses.geonames_city.nuts_level3.name	Name of the NUTS level 3 region that the organization is located in, from Geonames database	DEPRECATED. This field does not have a value in new and recently updated records, and values in existing records are not maintained.
addresses.lat	Latitude of the location identified in `addresses.geonames_city.id`, from Geonames database	Derived from the Geonames record for the ID addresses.geonames_city.id
addresses.line	A line of the address for the organization	DEPRECATED. Value is null or empty string for all ROR records.
addresses.lng	Longitude of the location identified in `addresses.geonames_city.id`, from Geonames database	Derived from the Geonames record for the ID addresses.geonames_city.id
addresses.postcode	Postcode/zipcode that the organization is located in	DEPRECATED. Value is null for most records. A small number of records inherited from GRID have lat/long data incorrectly stored in this field. This will be corrected in a future ROR data release.
addresses.primary	If there is more than one address, identifies the main location	DEPRECATED. Value is false in all ROR records.
addresses.state	State that the organization is located in	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained. SUPERSEDED by `addresses.geonames_city.geonames_admin1.name`
addresses.state_code	Code for the state that the organization is located in	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained. SUPERSEDED by `addresses.geonames_city.geonames_admin1.code`
aliases	Other names the organization is known by
country.country_code	ISO 3166-2 code for the country that the organization is located in, from Geonames database	Derived from the Geonames record for the ID addresses.geonames_city.id
country.country_name	Name of the country that the organization is located in, from Geonames database	Derived from the Geonames record for the ID addresses.geonames_city.id
email_address	A contact mail address for the organization	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained.
established	Year the organization was established (CE)
external_ids.CNRS.all	All CNRS identifiers for the organization	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained.
external_ids.CNRS.preferred	Preferred CNRS identifier for the organization, if one exists	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained.
external_ids.Fundref.all	All Fundref (Crossref Funder Registry) identifiers for the organization
external_ids.Fundref.preferred	Preferred Fundref (Crossref Funder Registry) identifier for the organization, if one exists
external_ids.GRID.all	All GRID identifiers for the organization	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained. Public GRID registry no longer exists.
external_ids.GRID.preferred	Preferred GRID identifier for the organization, if one exists	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained. Public GRID registry no longer exists.
external_ids.HESA.all	All HESA identifiers for the organization	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained.
external_ids.HESA.preferred	Preferred HESA identifier for the organization, if one exists	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained.
external_ids.ISNI.all	All ISNI identifiers for the organization
external_ids.ISNI.preferred	Preferred ISNI identifier for the organization, if one exists
external_ids.OrgRef.all	All OrgRef identifiers for the organization	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained. OrgRef registry no longer exists.
external_ids.OrgRef.preferred	Preferred OrgRef identifier for the organization, if one exists	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained. OrgRef registry no longer exists.
external_ids.UCAS.all	All UCAS identifiers for the organization	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained.
external_ids.UCAS.preferred	Preferred UCAS identifier for the organization, if one exists	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained.
external_ids.UKPRNS.all	All UKPRNS identifiers for the organization	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained.
external_ids.UKPRNS.preferred	Preferred UKPRNS identifier for the organization, if one exists	DEPRECATED. This field does not have a value in new records and values in existing records are not maintained.
external_ids.Wikidata.all	All Wikidata identifiers for the organization
external_ids.Wikidata.preferred	Preferred Wikidata identifier for the organization, if one exists
id	Unique ROR ID for the organization	Value is full ROR ID URL
ip_addresses	IP address(es) associated with the organization	DEPRECATED. This field does not have a value in new or existing records. Records inherited from GRID did not have values in this field.
labels.iso639	ISO 639-1 language code that identifies the language of a value in `labels.label`
labels.label	Name for the organization in another language
links	Official website of the organization	This field supports multiple URLs, but in practice, each record has either 1 or 0 URLs.
name	The primary name of the organization
relationships.id	Unique ROR ID of another organization which is related to the organization	Value is full ROR ID URL
relationships.label	Name of another organization identified in `relationships.id`, which is related to the organization
relationships.type	Type of relationship between the organization and another organization identified in `relationships.id`	Allowed relationship types: Parent, Child, Related
status	Whether the organization is active or not	All records currently have a value of "Active" in this field
types	Organization type	Allowed types: Education, Healthcare, Company, Archive, Nonprofit, Government, Facility, Other
wikipedia_url	Wikipedia page link for the organization

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"
            },
...

API advanced search

Example queries

Search all fields

Search a single field

Search multiple fields

Search all subfields of a parent field

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

🚧
Null vs empty string

Paging

Filtering

Errors & troubleshooting

Incorrect field names

Multiple query parameters

Unescaped reserved characters

Search strings with spaces

Available fields

How is this different from the existing ?query search?

Example queries

Search all fields

Search a single field

Search multiple fields

Search all subfields of a parent field

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

🚧Null vs empty string

Paging

Filtering

Errors & troubleshooting

Incorrect field names

Multiple query parameters

Unescaped reserved characters

Search strings with spaces

Available fields

How is this different from the existing ?query search?

🚧
Null vs empty string