# University Domains

> Look up universities by their email domains from a workflow. The University Domains and Names list holds about 10,000 universities in 200 countries, each with its name, its country and ISO code, the state or province where the list names one, every email domain it uses and its web pages. Turn a signup address into a university and a country, screen a whole list of addresses at once and optionally require a country, or find a university by name, by country and state, or by domain ending such as ac.uk. A departmental address resolves upwards, so an address at cs.usc.edu finds the University of Southern California. Every action reads: nothing here changes anything, in the list or anywhere else. No account or API key required.

App · Research & Academia · 8 actions. Web page: https://docs.lodol.com/docs/integrations/university-domains

## Actions

### Find universities by domain

Find the universities that use a domain, or an ending of one. 'ac.uk' returns the British universities, 'edu.tr' the Turkish ones, and an exact domain returns whoever holds it, which is more than one university for four domains in the list. A suffix only counts at a dot, so 'ac.uk' cannot match a domain that merely ends in those letters. Use this to work out what an academic domain looks like in a country before you write a rule about it. No API key required.

**Inputs**

- Domain or ending (`domain`, text, required): The domain or the ending to look for, such as 'ac.uk', 'edu.tr' or 'mit.edu'. A leading 'www.', a scheme and a path are all stripped, so a pasted URL works.
- How to match (`match`, text): How the text has to line up with a domain. 'Ends with' is the default and only counts whole labels, so 'ac.uk' finds ox.ac.uk. 'Contains' is looser and will find a fragment anywhere. One of: `suffix` (The domain ends with this, e.g. ac.uk), `contains` (The domain contains this anywhere), `exact` (The domain is exactly this). Default: `suffix`.
- Country (`country`, text): Only universities in this country. Takes an ISO 3166 alpha-2 code (TR, JP, GB), the name the list writes, or a common alias: 'Turkey' reaches Turkiye, 'South Korea' reaches Korea, Republic of, and 'UK' and 'USA' both work. The country is resolved to its code before anything is matched, which is what makes one filter find all 60 Vietnamese universities when the records spell the country two ways. Leave empty for every country. Run 'List countries' to see them.
- How many to return (`limit`, number): How many universities to return. The default of 25 keeps a step's result readable; raise it when a later step needs the whole set. From 1 to 500. Default: `25`.

**Outputs**

- `catalog_size` (number): How many universities the list holds
- `count` (number): How many are returned
- `country` (object): The country the filter resolved to, or null if none was given
- `match` (text): How it was matched, after any alias
- `match_count` (number): How many matched before the limit
- `query` (text): The domain searched for, after cleaning
- `source_url` (text): The project the list comes from
- `truncated` (true/false): Whether the limit cut the answer short
- `universities` (list): The matches, in domain order, each saying which of its domains matched

**Example output**

```json
{
  "catalog_size": 10259,
  "count": 1,
  "country": null,
  "match": "suffix",
  "match_count": 177,
  "query": "ac.uk",
  "source_url": "https://github.com/Hipo/university-domains-list",
  "truncated": true,
  "universities": [
    {
      "country": "United Kingdom",
      "country_code": "GB",
      "domain": "oxford.ac.uk",
      "domains": [
        "oxford.ac.uk",
        "ox.ac.uk"
      ],
      "matched_domains": [
        "oxford.ac.uk",
        "ox.ac.uk"
      ],
      "name": "University of Oxford",
      "state_province": null,
      "web_page": "http://www.ox.ac.uk/",
      "web_pages": [
        "http://www.ox.ac.uk/"
      ]
    }
  ]
}
```

### Get a university

Get one university's full record by name: its country and alpha-2 code, the state or province if the list names one, every email domain it uses and every web page it lists. The name is matched from most to least specific and stops at the first step that gives exactly one answer, so a partial name still works. A name that several universities share says which ones and where rather than picking one, because six of them are called Arab Open University. No API key required.

**Inputs**

- University name (`name`, text, required): The university's name, whole or partial. Case, accents and punctuation are ignored, so a name read off an earlier step goes straight back in.
- Country (`country`, text): Which country to look in, when a name is shared. Takes an alpha-2 code, the name the list writes, or a common alias. Leave empty to search every country.

**Outputs**

- `asked_for` (text): The name as it was given
- `catalog_size` (number): How many universities the list holds
- `country` (object): The country the filter resolved to, or null if none was given
- `found` (true/false): Always true; a name that matches nothing fails the step with a message instead
- `source_url` (text): The project the list comes from
- `university` (object): The university's full record

**Example output**

```json
{
  "asked_for": "Middle East Technical University",
  "catalog_size": 10259,
  "country": null,
  "found": true,
  "source_url": "https://github.com/Hipo/university-domains-list",
  "university": {
    "country": "Turkiye",
    "country_code": "TR",
    "domain": "metu.edu.tr",
    "domains": [
      "metu.edu.tr"
    ],
    "name": "Middle East Technical University",
    "state_province": null,
    "web_page": "http://www.metu.edu.tr/",
    "web_pages": [
      "http://www.metu.edu.tr/"
    ]
  }
}
```

### Identify a university by email

Say which university an email address belongs to, from the address alone. Give it 'ada@cs.usc.edu' and it returns the University of Southern California with its country, its domains and its web pages, because a subdomain is walked up to the domain the list actually holds. A bare domain works just as well as an address. Use this to turn a signup email into a university and a country, or to gate a workflow on whether an address is academic at all. No API key required.

**Inputs**

- Email address or domain (`email`, text, required): The address to identify, such as 'ada@cs.usc.edu', or a bare domain such as 'usc.edu'. A subdomain is walked up to its parent, so a departmental address finds the university. A pasted web page URL works too.

**Outputs**

- `catalog_size` (number): How many universities the list holds
- `checked_domains` (list): The domains tried, most specific first
- `domain` (text): The domain read out of it, lower-cased and without a leading 'www.'
- `input` (text): The address or domain as it was given
- `is_university` (true/false): Whether that domain is in the list. False is not proof it is not a university: the list is maintained by volunteers
- `match_count` (number): How many universities claim that domain; four domains in the list are claimed by two
- `matched_domain` (text): The listed domain that matched, as the list writes it, which may still carry a 'www.'
- `matched_on` (text): 'exact_domain', 'parent_domain' when a subdomain resolved upwards, or 'none'
- `source_url` (text): The project the list comes from
- `universities` (list): Every university that claims the domain
- `university` (object): The matching university, or null. The first of 'universities' when a domain is shared

**Example output**

```json
{
  "catalog_size": 10259,
  "checked_domains": [
    "cs.usc.edu",
    "usc.edu"
  ],
  "domain": "cs.usc.edu",
  "input": "ada@cs.usc.edu",
  "is_university": true,
  "match_count": 1,
  "matched_domain": "usc.edu",
  "matched_on": "parent_domain",
  "source_url": "https://github.com/Hipo/university-domains-list",
  "universities": [
    {
      "country": "United States",
      "country_code": "US",
      "domain": "usc.edu",
      "domains": [
        "usc.edu",
        "isi.edu"
      ],
      "name": "University of Southern California",
      "state_province": null,
      "web_page": "http://www.usc.edu/",
      "web_pages": [
        "http://www.usc.edu/",
        "http://www.isi.edu/"
      ]
    }
  ],
  "university": {
    "country": "United States",
    "country_code": "US",
    "domain": "usc.edu",
    "domains": [
      "usc.edu",
      "isi.edu"
    ],
    "name": "University of Southern California",
    "state_province": null,
    "web_page": "http://www.usc.edu/",
    "web_pages": [
      "http://www.usc.edu/",
      "http://www.isi.edu/"
    ]
  }
}
```

### List countries

List the countries the data covers, with how many universities, domains and states each one holds. This is also how you find the spelling a country filter wants: the list writes names in ISO 3166 long form, so it holds 'Turkiye' rather than 'Turkey' and 'Korea, Republic of' rather than 'South Korea'. Search by name or by alpha-2 code to check one. No API key required.

**Inputs**

- Search for (`query`, text): Only countries whose name contains this text, or whose alpha-2 code is exactly it. Case and accents are ignored. Leave empty for all of them.
- Sort by (`sort_by`, text): What order the countries come back in. Largest first by default, which puts the United States, Japan and India at the top. One of: `universities` (Most universities first), `name` (Country name), `code` (ISO alpha-2 code). Default: `universities`.
- How many to return (`limit`, number): How many countries to return. The list covers about 200, so the default of 250 returns all of them. From 1 to 300. Default: `250`.

**Outputs**

- `count` (number): How many are returned
- `countries` (list): The countries, in the order asked for
- `country_count` (number): How many countries the list covers in all
- `match_count` (number): How many countries matched the search
- `query` (text): The text searched for, or null
- `sort_by` (text): The order used, after any alias
- `source_url` (text): The project the list comes from
- `total_universities` (number): How many universities it holds in all
- `truncated` (true/false): Whether the limit cut the answer short

**Example output**

```json
{
  "count": 2,
  "countries": [
    {
      "country": "United States",
      "country_code": "US",
      "domain_count": 2393,
      "other_spellings": [],
      "state_count": 38,
      "university_count": 2348
    },
    {
      "country": "Viet Nam",
      "country_code": "VN",
      "domain_count": 61,
      "other_spellings": [
        "Vietnam"
      ],
      "state_count": 4,
      "university_count": 60
    }
  ],
  "country_count": 200,
  "match_count": 200,
  "query": null,
  "sort_by": "universities",
  "source_url": "https://github.com/Hipo/university-domains-list",
  "total_universities": 10259,
  "truncated": true
}
```

### List universities in a country

List every university the data holds for one country, sorted and paged. Narrow to a state or province, and see which ones that country actually names, since the field is filled in on only about one record in seven. The country is resolved to its ISO code first, which is why this returns all 60 Vietnamese universities where a search for the literal string 'Vietnam' would return 10. No API key required.

**Inputs**

- Country (`country`, text, required): The country to list. Takes an ISO 3166 alpha-2 code (JP, TR, GB), the name the list writes, or a common alias: 'Turkey' reaches Turkiye and 'South Korea' reaches Korea, Republic of. Run 'List countries' to see them all.
- State or province (`state_province`, text): Only universities in this state or province. Matched loosely and without regard to case or accents, because the field is free text written by whoever added the record. It is empty on 8,886 of the 10,259 records, so treat it as an extra rather than as coverage you can rely on; 'List universities in a country' reports the ones a country actually names. Leave empty for all of them.
- Sort by (`sort_by`, text): What order the universities come back in. By name by default. Sorting by state puts the records that name one first, since most name none. One of: `name` (University name), `country` (Country, then name), `state_province` (State or province, then name), `domain`. Default: `name`.
- How many to return (`limit`, number): How many universities to return. The default of 25 keeps a step's result readable; raise it when a later step needs the whole set. From 1 to 500. Default: `25`.
- Skip this many (`offset`, number): How many to skip before returning, for paging through a large country. The United States holds 2,348 universities, so a second step at an offset of 500 continues where the first left off. At least 0. Default: `0`.

**Outputs**

- `catalog_size` (number): How many universities the list holds
- `count` (number): How many are returned
- `country` (object): The country the filter resolved to, or null if none was given
- `match_count` (number): How many matched before limit and offset
- `offset` (number): How many were skipped
- `source_url` (text): The project the list comes from
- `state_count` (number): How many of them there are
- `state_province` (text): The state filter used, or null
- `states` (list): Every state or province this country names, grouped without regard to case
- `truncated` (true/false): Whether there are more after this page
- `universities` (list): The universities on this page

**Example output**

```json
{
  "catalog_size": 10259,
  "count": 1,
  "country": {
    "country": "Turkiye",
    "country_code": "TR",
    "other_spellings": [],
    "university_count": 188
  },
  "match_count": 188,
  "offset": 0,
  "source_url": "https://github.com/Hipo/university-domains-list",
  "state_count": 12,
  "state_province": null,
  "states": [
    "Adana",
    "Afyonkarahisar",
    "Ankara"
  ],
  "truncated": true,
  "universities": [
    {
      "country": "Turkiye",
      "country_code": "TR",
      "domain": "metu.edu.tr",
      "domains": [
        "metu.edu.tr"
      ],
      "name": "Middle East Technical University",
      "state_province": null,
      "web_page": "http://www.metu.edu.tr/",
      "web_pages": [
        "http://www.metu.edu.tr/"
      ]
    }
  ]
}
```

### Search universities by name

Search the list by university name and get the closest matches first: the exact name, then the ones that start with the text, then the ones where every word appears. Accents and punctuation are folded, so 'santa maria' finds Universidad Tecnica Federico Santa Maria. Narrow by country or by state as well. Use this when you know roughly what the university is called but not how the list spells it. No API key required.

**Inputs**

- Search for (`query`, text, required): The text to look for in a university's name. At least two characters. Case, accents and punctuation are ignored.
- Country (`country`, text): Only universities in this country. Takes an ISO 3166 alpha-2 code (TR, JP, GB), the name the list writes, or a common alias: 'Turkey' reaches Turkiye, 'South Korea' reaches Korea, Republic of, and 'UK' and 'USA' both work. The country is resolved to its code before anything is matched, which is what makes one filter find all 60 Vietnamese universities when the records spell the country two ways. Leave empty for every country. Run 'List countries' to see them.
- State or province (`state_province`, text): Only universities in this state or province. Matched loosely and without regard to case or accents, because the field is free text written by whoever added the record. It is empty on 8,886 of the 10,259 records, so treat it as an extra rather than as coverage you can rely on; 'List universities in a country' reports the ones a country actually names. Leave empty for all of them.
- How to match (`match`, text): How the text has to appear in the name. 'Contains' is the default and the most forgiving. 'Every word' is what finds a name whose middle word you left out, since order does not matter and a word only has to start one of the name's. One of: `contains` (The name contains the text anywhere), `starts_with` (The name starts with the text), `words` (Every word of the text appears, in any order), `exact` (The whole name is the text). Default: `contains`.
- How many to return (`limit`, number): How many universities to return. The default of 25 keeps a step's result readable; raise it when a later step needs the whole set. From 1 to 500. Default: `25`.

**Outputs**

- `catalog_size` (number): How many universities the list holds
- `count` (number): How many are returned
- `country` (object): The country the filter resolved to, or null if none was given
- `match` (text): How it was matched, after any alias
- `match_count` (number): How many matched before the limit
- `query` (text): The text searched for
- `source_url` (text): The project the list comes from
- `state_province` (text): The state filter used, or null
- `truncated` (true/false): Whether the limit cut the answer short
- `universities` (list): The matches, closest first

**Example output**

```json
{
  "catalog_size": 10259,
  "count": 1,
  "country": {
    "country": "Turkiye",
    "country_code": "TR",
    "other_spellings": [],
    "university_count": 188
  },
  "match": "contains",
  "match_count": 1,
  "query": "middle east",
  "source_url": "https://github.com/Hipo/university-domains-list",
  "state_province": null,
  "truncated": false,
  "universities": [
    {
      "country": "Turkiye",
      "country_code": "TR",
      "domain": "metu.edu.tr",
      "domains": [
        "metu.edu.tr"
      ],
      "name": "Middle East Technical University",
      "state_province": null,
      "web_page": "http://www.metu.edu.tr/",
      "web_pages": [
        "http://www.metu.edu.tr/"
      ]
    }
  ]
}
```

### Summarize the university list

Get the whole list in numbers: how many universities from how many countries, how many distinct domains they use, how many list more than one, how many domains two universities share, how many names are shared, how many records name a state, the largest countries with their share, and the domain endings that come up most. Use it to size a job before running it, or to report on coverage. No API key required.

**Inputs**

- How many countries to rank (`top_countries`, number): How many of the largest countries to list, with each one's share of the whole. From 1 to 50. Default: `10`.

**Outputs**

- `country_count` (number): How many countries they sit in
- `data_url` (text): The JSON file this integration reads
- `domain_count` (number): How many distinct email domains are listed
- `multi_domain_count` (number): How many universities list more than one domain
- `shared_domain_count` (number): How many domains two universities both claim
- `shared_name_count` (number): How many names more than one university uses, compared without case, accents or punctuation
- `source_url` (text): The project the list comes from
- `top_countries` (list): The largest countries, most universities first
- `top_domain_suffixes` (list): The most common domain endings
- `total_universities` (number): How many universities the list holds
- `with_state_province` (number): How many records name a state or province

**Example output**

```json
{
  "country_count": 200,
  "data_url": "https://raw.githubusercontent.com/Hipo/university-domains-list/master/world_universities_and_domains.json",
  "domain_count": 10578,
  "multi_domain_count": 281,
  "shared_domain_count": 4,
  "shared_name_count": 89,
  "source_url": "https://github.com/Hipo/university-domains-list",
  "top_countries": [
    {
      "country": "United States",
      "country_code": "US",
      "share_percent": 22.9,
      "university_count": 2348
    },
    {
      "country": "Japan",
      "country_code": "JP",
      "share_percent": 5.6,
      "university_count": 572
    }
  ],
  "top_domain_suffixes": [
    {
      "domain_count": 2618,
      "suffix": "edu"
    },
    {
      "domain_count": 565,
      "suffix": "ac.jp"
    }
  ],
  "total_universities": 10259,
  "with_state_province": 1373
}
```

### Verify a list of email domains

Check a batch of email addresses against the list in one step and get a verdict for each: whether it is a university address, which university, and in which country. Optionally require a country, so 'is this a Japanese university address' is one field rather than a second step. Built for screening a signup sheet or a spreadsheet column, so the result carries the pass and fail counts and the entries that failed as well as the rows themselves. Takes up to 200 entries and reads the list once for all of them. No API key required.

**Inputs**

- Addresses or domains (`emails`, list, required): The addresses to check, up to 200. Takes a list from an earlier step, or text with one entry per line or separated by commas. Bare domains are fine alongside full addresses. An entry that is not an address at all is reported as a failed row rather than stopping the step.
- Require this country (`country`, text): When set, a row only passes if its university is in this country. Takes an alpha-2 code, the name the list writes, or a common alias. Leave empty to accept a university anywhere.

**Outputs**

- `all_passed` (true/false): Whether every entry passed
- `catalog_size` (number): How many universities the list holds
- `checked` (number): How many entries were checked
- `fail_count` (number): How many did not
- `failed` (list): The entries that failed, as they were given
- `not_found_count` (number): How many did not
- `pass_count` (number): How many met every requirement
- `required_country` (object): The country the filter resolved to, or null if none was given
- `results` (list): One verdict per entry, in the order given
- `source_url` (text): The project the list comes from
- `university_count` (number): How many resolved to a university

**Example output**

```json
{
  "all_passed": false,
  "catalog_size": 10259,
  "checked": 2,
  "fail_count": 1,
  "failed": [
    "bob@cs.usc.edu"
  ],
  "not_found_count": 0,
  "pass_count": 1,
  "required_country": {
    "country": "Turkiye",
    "country_code": "TR",
    "other_spellings": [],
    "university_count": 188
  },
  "results": [
    {
      "country": "Turkiye",
      "country_code": "TR",
      "domain": "metu.edu.tr",
      "in_country": true,
      "input": "ada@metu.edu.tr",
      "is_university": true,
      "matched_domain": "metu.edu.tr",
      "matched_on": "exact_domain",
      "passes": true,
      "reason": "",
      "state_province": null,
      "university": "Middle East Technical University"
    },
    {
      "country": "United States",
      "country_code": "US",
      "domain": "cs.usc.edu",
      "in_country": false,
      "input": "bob@cs.usc.edu",
      "is_university": true,
      "matched_domain": "usc.edu",
      "matched_on": "parent_domain",
      "passes": false,
      "reason": "University of Southern California is in United States, not Turkiye.",
      "state_province": null,
      "university": "University of Southern California"
    }
  ],
  "source_url": "https://github.com/Hipo/university-domains-list",
  "university_count": 2
}
```