US College Institutions API Guide

Search college reference records for school discovery, comparison tools, and education research. Results include location, tuition, admissions, completion, enrollment, and source dates. They are not a live tuition quote or an admissions decision; check the institution for current requirements and costs.

Request

Send a GET request with your AppKey in the query string. Encode each filter separately so spaces, plus signs, and ampersands retain their meaning.

curl --get 'https://api.gugudata.io/v1/education/us/institutions/search' \
  --data-urlencode 'appkey=YOUR_APPKEY' \
  --data-urlencode 'name=Harvard' \
  --data-urlencode 'state=MA' \
  --data-urlencode 'sort=tuition|asc' \
  --data-urlencode 'pageIndex=1' \
  --data-urlencode 'pageSize=10'

Parameter	Behavior
name	Case-insensitive name or alias substring.
state	Case-insensitive state abbreviation match.
city	Case-insensitive city substring.
ownership, degreeLevel	Case-insensitive text filters.
minAdmissionRate	Finite value from 0 to 1, inclusive.
maxTuition	Finite non-negative maximum in-state tuition.
sort	institutionName, tuition, admissionRate, or graduationRate, followed by `
pageIndex	Default 1. Values below 1 use 1 for compatibility.
pageSize	Default 10. Values below 1 use 10; values above 100 use 100.

Text filters and sort accept at most 100 Unicode code points after NFKC normalization and trimming. Control characters are rejected. Missing text filters do not restrict the search. Sorting includes stable tie-breakers.

Response

Successful responses use HTTP 200 and business code 100. data is an array of institution objects. dataStatus.dataTotalCount counts all matching records, not just the current page. No matches return an empty array; a page beyond the end also returns an empty array while preserving the matching total.

Each record contains the following fields. Numeric fields may be null when unavailable; do not treat missing tuition or rates as zero. Missing text is an empty string.

Fields	Type and meaning
unitId	Integer or null; institution identifier.
opeId, scorecardId	String identifiers.
institutionName, city, state, zip, website	Strings describing the institution and location.
ownership, degreeLevel, institutionType	Classification strings.
studentSize, sourceYear	Integers or null.
admissionRate, completionRate	Numbers or null.
tuitionInState, tuitionOutOfState, netPricePublic, netPricePrivate	Numbers or null; cost reference values.
source, sourceUpdatedAt	Source label and source update timestamp strings.

The response timestamp uses yyyy-MM-dd HH:mm:ss.SSS. Review each record’s source year and update timestamp before comparing figures across institutions.

Demo and errors

The Demo queries the first five institution records and caches validated results for 15 minutes. X-GuGuData-Demo-Mode is live or cached; X-GuGuData-Generated-At identifies when the cached result was generated. Failed results are not cached.

Invalid filters return HTTP/business 400. Temporary data unavailability returns HTTP 503 with business code 500. Authentication, entitlement, and rate-limit failures retain their standard 401, 403, and 429 HTTP responses. Check HTTP and business status before processing records; never turn a failed request into an empty search result.

See the API details and OpenAPI specification for integration reference.