POST /api/collegenavigator/institutions/search
Price: 5 credits
Search US postsecondary institutions in NCES College Navigator by name, state, ZIP radius, programme, award level, control, level, tuition, enrolment, campus setting, admission rate, SAT and ACT scores, housing, varsity sport, online and evening options, religious affiliation and special mission. Each result carries the UNITID, OPE ID, name, address, phone, type, awards offered, campus setting, housing, student population and student-to-faculty ratio
A query reaches at most 500 institutions; narrow by state, control or level to reach the rest. Pass a returned id to collegenavigator/institutions for the full profile and programme completions.
access-token string requiredtimeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)name string nullable — Words that must all appear in the institution name (examples: "harvard"; minLength: 1)states array nullable — US states or territories, as postal codes or names (examples: ["CA","New York"])zip_code string nullable — ZIP code to search around, with distance_miles (examples: "02912")distance_miles integer nullable — Radius around zip_code in miles: 5, 10, 15, 20, 25, 50, 100, 150, 200 or 250 (examples: 25)programs array nullable — CIP 2020 programme codes or two-digit programme families the institution must offer (examples: ["51.3801"], ["14"])programs_by_distance_education boolean — Only institutions offering the chosen programmes as distance education (default: false; examples: true)match_all_programs boolean — Require every chosen programme instead of any of them (default: false; examples: true)award_levels array nullable — Award levels offered (one of: "Certificate", "Associate's", "Bachelor's", "Advanced"; examples: ["Bachelor's","Advanced"])controls array nullable — Institution control (one of: "Public", "Private not-for-profit", "Private for-profit"; examples: ["Public","Private not-for-profit"])levels array nullable — Institution level by longest programme (one of: "4-year", "2-year", "< 2-year"; examples: ["4-year"])max_tuition integer nullable — Maximum yearly tuition and fees in US dollars, from 500 to 60000 (examples: 20000)tuition_state string nullable — Home state the max_tuition applies to, for in-state public tuition (examples: "NY")min_undergraduate_enrollment integer nullable — Minimum undergraduate enrolment, from 100 to 30000 (examples: 1000)max_undergraduate_enrollment integer nullable — Maximum undergraduate enrolment, from 100 to 30000 (examples: 10000)locales array nullable — Campus setting (one of: "City", "Suburban", "Town", "Rural"; examples: ["City","Suburban"])min_admission_rate integer nullable — Minimum percent of applicants admitted, from 5 to 100 (examples: 10)max_admission_rate integer nullable — Maximum percent of applicants admitted, from 5 to 100 (examples: 30)min_sat_reading integer nullable — Minimum SAT reading and writing 25th percentile, 200 to 800 (examples: 600)max_sat_reading integer nullable — Maximum SAT reading and writing 75th percentile, 200 to 800 (examples: 800)min_sat_math integer nullable — Minimum SAT math 25th percentile, 200 to 800 (examples: 600)max_sat_math integer nullable — Maximum SAT math 75th percentile, 200 to 800 (examples: 800)min_act integer nullable — Minimum ACT composite 25th percentile, 2 to 34 (examples: 24)max_act integer nullable — Maximum ACT composite 75th percentile, 2 to 34 (examples: 34)has_campus_housing boolean — Only institutions with campus housing (default: false; examples: true)sport string nullable — Varsity sport offered, with sport_men and sport_women (examples: "Basketball")sport_men boolean — The varsity sport has a men's team (default: false; examples: true)sport_women boolean — The varsity sport has a women's team (default: false; examples: true)distance_learning_only boolean — Only institutions offering programmes entirely online (default: false; examples: true)weekend_evening boolean — Only institutions with weekend or evening college (default: false; examples: true)credit_for_life_experience boolean — Only institutions granting credit for life experience (default: false; examples: true)religious_affiliation string nullable — Religious affiliation (examples: "Roman Catholic", "Not applicable")special_mission string nullable — Special mission (one of: "Single-sex: Men", "Single-sex: Women", "Historically Black College or University", "Tribal College"; examples: "Historically Black College or University")sort string — Sort order of the results; distance needs zip_code (default: "name"; one of: "name", "city", "state", "distance"; examples: "name")sort_descending boolean — Sort in descending order (default: false; examples: true)count integer required — Max number of institutions to return (min: 1; max: 500)@type string (default: "CollegeNavigatorInstitutionCard")id string requiredope_id string nullablename string requiredurl string requiredaddress string nullablestreet string nullablecity string nullablestate string nullablestate_code string nullablezip_code string nullablephone string nullablelevel string nullableaward_focus string nullablecontrol string nullableis_distance_education_only boolean (default: false)has_failed_90_10_requirement boolean (default: false)failed_90_10_fiscal_year integer nullabledistance_miles number nullableawards_offered array (default: [])campus_setting string nullablehas_campus_housing boolean nullablestudent_count integer nullableundergraduate_student_count integer nullablestudent_faculty_ratio number nullable422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.412 — No institution matches these filters Retrying will not help: either the entity does not exist, or the input points at a different one.429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.X-Error — Error message text (present only on error)X-Request-ID — Unique request identifierX-Execution-Time — Execution time in secondsX-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.X-Retry-After — Seconds to wait before retrying. Present only on 429.