# US College Institutions Data API
Search standardized US college and university data.
## API Overview
- **HTTP Protocol:** HTTPS
- **HTTP Method:** GET
- **HTTP Endpoint:** https://api.gugudata.io/v1/education/us/institutions/search
- **Response Type:** application/json; charset=utf-8
- **DEMO Endpoint:** https://api.gugudata.io/v1/education/us/institutions/demo
- **Live Demo:** https://gugudata.io/demo/us-college-institutions
- **Postman:** https://www.postman.com/gugudata/gugudata-io
- **LLM Page:** https://gugudata.io/details/us-college-institutions/llm
- **Raw Markdown:** https://gugudata.io/details/us-college-institutions/llm.md
## Remote MCP
- **MCP Endpoint:** https://mcp.gugudata.io/mcp
- **MCP Guide:** https://gugudata.io/mcp/
- **Authorization:** OAuth authorization opens in the browser; do not paste appkeys into MCP clients.
- **Tool Scope:** MCP clients receive GuGuData API tools available to the authorized account.
## Data & API Features
- College discovery: Find institutions by name, alias, city, or state.
- Education filters: Narrow results by ownership and degree level.
- Cost comparisons: Review available tuition and net-price reference values.
- Admissions context: Compare reported admission and completion rates where available.
- Paginated records: Browse sorted institution records with matching totals.
- Source dates: Check source years and update timestamps when interpreting records.
## API Request Parameters
| Name | Type | Is Required | Default Value | Remark |
| --- | --- | --- | --- | --- |
| appkey | string | true | YOUR_APPKEY | API key used to authenticate the request. |
| name | string | false | | Institution name keyword. |
| state | string | false | | US state abbreviation, such as CA or MA. |
| city | string | false | | City name keyword. |
| ownership | string | false | | Ownership filter, such as public or private. |
| degreeLevel | string | false | | Degree level keyword. |
| minAdmissionRate | number | false | | Minimum admission rate. |
| maxTuition | number | false | | Maximum in-state tuition. |
| sort | string | false | institutionName\|asc | Sort field and direction. Supported fields: institutionName, tuition, admissionRate, graduationRate. |
| pageIndex | integer | false | 1 | Page number for pagination. |
| pageSize | integer | false | 10 | Number of records per page. |
## API Response Parameters
| Name | Type | Remark |
| --- | --- | --- |
| dataStatus.dataTotalCount | integer | Number of matching or returned records for this request. |
| data[].unitId | integer | IPEDS UNITID. |
| data[].institutionName | string | Institution name. |
| data[].state | string | US state. |
| data[].website | string | Institution website. |
| data[].admissionRate | number | Admission rate when available. |
| data[].tuitionInState | number | In-state tuition when available. |
| data[].sourceYear | integer | Source data year. |
| data[].sourceUpdatedAt | string | Source update timestamp. |
## API Response Status Codes
| Status Code | Explanation of Status Code | Remarks |
| --- | --- | --- |
| 200 | Request processed successfully. | Some endpoints expose a separate application-level status field in the response body, such as `dataStatus.statusCode`. |
| 400 | Invalid request parameters or request format. | Check required fields, data types, and request body format. |
| 401 | Missing or unknown application key. | Provide a valid `appkey` with the request. |
| 403 | The application key is recognized but access is not allowed. | The key may be expired, inactive, or not permitted for the requested API. |
| 429 | Request rate or trial usage limit exceeded. | Reduce request frequency and retry with backoff. If a trial allowance is exhausted, check Trial Keys for remaining requests and subscribe to continue. |
| 500 | Internal service error. | Retry later or contact support if the error persists. |
| 503 | Upstream service unavailable. | Retry later; the requested upstream dependency is temporarily unavailable. |
## cURL Example
```bash
curl --location 'https://api.gugudata.io/v1/education/us/institutions/search?appkey=YOUR_APPKEY&name=YOUR_VALUE&state=YOUR_VALUE&city=YOUR_VALUE&ownership=YOUR_VALUE°reeLevel=YOUR_VALUE&minAdmissionRate=YOUR_VALUE&maxTuition=YOUR_VALUE&sort=institutionName%7Casc&pageIndex=1&pageSize=10'
```