---
agentTools:
  projectIndex: https://ror.readme.io/llms.txt
---

# 2022-10-24 Affiliation matching improvements (API only)

Based on user feedback, we've released a set of tweaks to ROR's [affiliation matching](https://ror.readme.io/docs/rest-api#affiliation-parameter) service focused on improving precision and reducing false positive results. The updated affiliation matching service is now available in production, at the existing affiliation matching endpoint `https://api.ror.org/organziations?affiliation=`. While the search behavior has changed slightly, request and response format remains remains unchanged. Many thanks to ROR integrators who helped to beta test these improvements! Read [the rest of this post](https://ror.readme.io/changelog/2022-10-24-affiliation-matching-improvements-api-only) for details about the changes.

## Change summary

### Check for exact matches first

* Previously, the entered string was split into multiple substrings and many searches were performed without checking to see if an exact match of the entered string existed in a ROR record.
* Now, a search for an exact match of the entered string in name, aliases, labels and acronyms fields is performed before performing additional searches. If there's an exact match with a perfect score of 1.0, the result is returned immediately and no further searches are performed. A new `matching_type` value `EXACT` is returned with any matches made using this method.

### De-prioritize acronym search results

* Previously, results generated using the  `matching_type: ACRONYM`, which extracts and search for any sets of 3 or more capitalized letters (except ISO3 country codes) from the original search string, were weighted similarly to other matching types. This produced many false positive results.
* Now, `matching_type: ACRONYM` does not produce results with `chosen` set to `True`.

### Don't mark multiple results as chosen = True

* Previously, multiple results with a value of `True` in the `chosen` field were sometimes returned.
* Now, `chosen` is only set to `True` if there is a single result that is a highly probable match. Multiple results with high scores indicate ambiguity, so `chosen` is set to `False` for all results in that case.

### Generate fewer search substrings

* Previously, for search strings containing multiple words, many substrings were generated and searched independently, resulting in many cases of false positive results (irrelevant substrings with high matching scores)
* Now, search strings are split into multiple substrings only at , (comma) ; (semicolon) and : (colon) characters. The full original search string is also included.

### Exclude search strings that match specific common phrases, country names, country codes and city names

* Previously, substrings which matched common phrases (such as "University Hospital"), country names/codes or city names produced many false positive results
* Now, substrings that match common phrases, country names, city names and iso2 or iso3 country codes are ignored.

### Strip special chars (except &) from search strings

* Previously, special characters were left untouched in search strings and generated substrings, which occasionally resulted in errors or "missed" matches.
* Now, special characters (except &) are stripped from search strings and substrings

### Only return results with a score of >= .5

* Previously, all results were included in the result set.
* Now, only results with a matching score >= .5 are included in the result set.

### 12 character minimum no longer required

* Previously, 0 results were returned for search strings of < 12 characters, unless an exact match as found.
* Now, there is no minimum character threshold.

## Usage

Changes above are currently available in the existing affiliation matching endpoint, `https://api.ror.org/organizations?affiliation=`

The only usage changes that have been made are:

* A minimum of 12 characters is no longer required
* In results, a new matching\_type `EXACT` has been added

All other usage remains as described in [REST API > Search ROR Records > Affiliation parameter](https://ror.readme.io/docs/rest-api#affiliation-parameter) for usage instructions.

Example query:

```curl
curl https://api.ror.org/organizations?affiliation=Department%20of%20Civil%20and%20Industrial%20Engineering%2C%20University%20of%20Pisa%2C%20Largo%20Lucio%20Lazzarino%202%2C%20Pisa%2056126%2C%20Italy
```