/collegescorecard/schools/search

POST /api/collegescorecard/schools/search

Price: 20 credits

Search US colleges and universities by name, state, distance from a ZIP code, ownership, predominant credential, enrolment size, operating status and minority-serving designation, ordered by enrolment, admission rate, net price, earnings or completion rate

How to use it

The name-searchable index of US institutions, and the way into both platforms: the `id` it returns is the IPEDS UNITID, so it feeds ipeds/institutions, collegescorecard/schools and collegescorecard/schools/programs unchanged. IPEDS itself has no name search, so start here whenever the user names an institution rather than a place. `name` matches words anywhere in the official name, which is why a campus is often found by its city as well. `zip_code` needs `distance_miles` to mean anything. Each result carries the profile plus a few headline numbers; the full outcome record, including debt, repayment and earnings, is collegescorecard/schools for one id. Institutions that have closed are included unless you set `operating_only`.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• count integer required — Max number of institutions to return (min: 1; max: 2000)
• name string nullable — Words that must appear in the institution name (examples: "harvard", "community college")
• state string nullable — Two-letter US state, DC or territory postal code (examples: "MA", "CA", "TX")
• zip_code string nullable — US ZIP code to search around, used together with distance_miles (examples: "02139")
• distance_miles integer nullable — Radius around zip_code in miles (min: 1; max: 1000)
• ownership string nullable — Who controls the institution (one of: "public", "private_nonprofit", "private_for_profit")
• predominant_degree string nullable — Credential the institution awards most of (one of: "not_classified", "certificate", "associate", "bachelors", "graduate")
• operating_only boolean — Only institutions that are still operating (default: false)
• closed_only boolean — Only institutions that have closed (default: false)
• men_only boolean — Only men's colleges (default: false)
• women_only boolean — Only women's colleges (default: false)
• historically_black_only boolean — Only historically Black colleges and universities (default: false)
• tribal_only boolean — Only tribal colleges and universities (default: false)
• min_enrolment integer nullable — Smallest undergraduate enrolment to accept (min: 0)
• max_enrolment integer nullable — Largest undergraduate enrolment to accept (min: 0)
• sort string nullable — Field the results are ordered by (one of: "enrolment", "name", "admission_rate", "average_cost", "median_earnings", "completion_rate")
• sort_direction string — Order of the sort field (default: "desc"; one of: "asc", "desc")

Response

• @type string (default: "CollegescorecardSchool")
• id string required
• ope6_id string nullable
• ope8_id string nullable
• federal_school_code string nullable
• latitude number nullable
• longitude number nullable
• school object nullable
  • @type string (default: "CollegescorecardSchoolProfile")
  • name string nullable
  • alternative_name string nullable
  • address string nullable
  • city string nullable
  • state string nullable
  • state_fips string nullable
  • zip_code string nullable
  • region string nullable
  • locale string nullable
  • web_url string nullable
  • price_calculator_url string nullable
  • accreditor string nullable
  • accreditor_code string nullable
  • ownership string nullable
  • ownership_peps string nullable
  • sector_code string nullable
  • level_code string nullable
  • predominant_degree_code string nullable
  • highest_degree_code string nullable
  • predominant_degree_recoded_code string nullable
  • carnegie_basic string nullable
  • carnegie_undergraduate_profile string nullable
  • carnegie_size_and_setting string nullable
  • religious_affiliation_code string nullable
  • degree_urbanization_code string nullable
  • branch_count integer nullable
  • is_main_campus boolean nullable
  • is_operating boolean nullable
  • is_online_only boolean nullable
  • is_men_only boolean nullable
  • is_women_only boolean nullable
  • has_open_admissions_policy boolean nullable
  • is_under_investigation boolean nullable
  • is_historically_black boolean nullable
  • is_predominantly_black boolean nullable
  • is_hispanic_serving boolean nullable
  • is_tribal boolean nullable
  • is_alaska_native_native_hawaiian_serving boolean nullable
  • is_asian_american_native_american_pacific_islander_serving boolean nullable
  • is_native_american_non_tribal_serving boolean nullable
  • has_dol_flag boolean nullable
  • title_iv_approved_at integer nullable
  • title_iv_eligibility_code string nullable
  • endowment_begin number nullable
  • endowment_end number nullable
  • faculty_salary number nullable
  • full_time_faculty_rate number nullable
  • instructional_expenditure_per_fte number nullable
  • tuition_revenue_per_fte number nullable
• students object nullable
  • @type string (default: "CollegescorecardStudentBody")
  • size integer nullable
  • size_category_code string nullable
  • undergraduate_12_month_count integer nullable
  • graduate_12_month_count integer nullable
  • graduate_student_count integer nullable
  • non_degree_seeking_undergraduate_count integer nullable
  • student_faculty_ratio number nullable
  • part_time_share number nullable
  • share_25_or_older number nullable
  • share_over_23_at_entry number nullable
  • share_married number nullable
  • share_veteran number nullable
  • share_female number nullable
  • share_first_generation number nullable
  • share_parents_middle_school number nullable
  • share_parents_high_school number nullable
  • share_independent number nullable
  • share_with_pell_grant number nullable
  • average_age_at_entry number nullable
  • average_family_income number nullable
  • average_family_income_dependent number nullable
  • average_family_income_independent number nullable
  • family_income_reported_count integer nullable
  • family_income_reported_count_dependent integer nullable
  • family_income_reported_count_independent integer nullable
  • parents_education_reported_count integer nullable
  • median_family_income number nullable
  • median_household_income number nullable
  • poverty_rate number nullable
  • unemployment_rate number nullable
  • fafsa_application_count integer nullable
  • retention_rate_full_time number nullable
  • retention_rate_part_time number nullable
  • student_race_shares object nullable
    • @type string (default: "CollegescorecardRaceShares")
    • white number nullable
    • black number nullable
    • hispanic number nullable
    • asian number nullable
    • american_indian_alaska_native number nullable
    • native_hawaiian_pacific_islander number nullable
    • two_or_more number nullable
    • non_resident_alien number nullable
    • unknown number nullable
  • faculty_race_shares object nullable
    • @type string (default: "CollegescorecardRaceShares")
    • white number nullable
    • black number nullable
    • hispanic number nullable
    • asian number nullable
    • american_indian_alaska_native number nullable
    • native_hawaiian_pacific_islander number nullable
    • two_or_more number nullable
    • non_resident_alien number nullable
    • unknown number nullable
  • share_men number nullable
  • share_women number nullable
  • faculty_share_men number nullable
  • faculty_share_women number nullable
• cost object nullable
  • @type string (default: "CollegescorecardCost")
  • attendance_academic_year number nullable
  • attendance_program_year number nullable
  • tuition_in_state number nullable
  • tuition_out_of_state number nullable
  • tuition_program_year number nullable
  • books_and_supplies number nullable
  • room_and_board_on_campus number nullable
  • room_and_board_off_campus number nullable
  • other_expenses_on_campus number nullable
  • other_expenses_off_campus number nullable
  • other_expenses_with_family number nullable
  • average_net_price number nullable
  • average_net_price_public number nullable
  • average_net_price_private number nullable
  • median_net_price_all_institutions number nullable
  • median_net_price_same_predominant_degree number nullable
  • title_iv_recipient_count integer nullable
  • net_price_by_income array (default: [])
    • @type string (default: "CollegescorecardNetPriceLine")
    • payer string nullable
    • income_band string nullable
    • net_price number nullable
    • title_iv_recipient_count integer nullable
• aid object nullable
  • @type string (default: "CollegescorecardAid")
  • pell_grant_rate number nullable
  • federal_loan_rate number nullable
  • share_with_any_loan number nullable
  • average_loan_principal number nullable
  • median_debt_overall number nullable
  • median_debt_completers number nullable
  • median_debt_noncompleters number nullable
  • median_debt_monthly_payment number nullable
  • median_debt_dependent_students number nullable
  • median_debt_independent_students number nullable
  • median_debt_first_generation_students number nullable
  • median_debt_non_first_generation_students number nullable
  • cumulative_debt_10th_percentile number nullable
  • cumulative_debt_25th_percentile number nullable
  • cumulative_debt_75th_percentile number nullable
  • cumulative_debt_90th_percentile number nullable
  • borrower_count integer nullable
  • parent_plus_median_debt number nullable
  • parent_plus_borrower_count integer nullable
  • direct_loan_amount number nullable
  • direct_loan_count integer nullable
• earnings array (default: [])
  • @type string (default: "CollegescorecardEarningsPeriod")
  • years_after integer nullable
  • measured_from string nullable
  • median_earnings number nullable
  • mean_earnings number nullable
  • earnings_10th_percentile number nullable
  • earnings_25th_percentile number nullable
  • earnings_75th_percentile number nullable
  • earnings_90th_percentile number nullable
  • share_earning_above_high_school_graduate number nullable
  • share_earning_above_25000 number nullable
  • share_earning_above_28000 number nullable
  • working_not_enrolled_count number nullable
  • not_working_not_enrolled_count number nullable
• completion object nullable
  • @type string (default: "CollegescorecardCompletion")
  • overall_rate number nullable
  • median_rate_by_predominant_degree number nullable
  • four_year_rate_150_percent number nullable
  • four_year_rate_150_percent_pooled number nullable
  • four_year_rate_150_percent_pell number nullable
  • transfer_rate_four_year_full_time number nullable
  • pooled_years_used integer nullable
  • cohorts array (default: [])
    • @type string (default: "CollegescorecardCompletionCohort")
    • years integer nullable
    • overall_count integer nullable
    • male_student_count integer nullable
    • female_student_count integer nullable
    • dependent_student_count integer nullable
    • independent_student_count integer nullable
    • first_generation_student_count integer nullable
    • non_first_generation_student_count integer nullable
    • low_income_student_count integer nullable
    • pell_grant_student_count integer nullable
    • no_pell_grant_student_count integer nullable
  • by_race array (default: [])
    • @type string (default: "CollegescorecardCompletionByRace")
    • race string nullable
    • completion_rate number nullable
    • cohort_count integer nullable
• repayment object nullable
  • @type string (default: "CollegescorecardRepayment")
  • two_year_default_rate number nullable
  • three_year_default_rate number nullable
  • two_year_default_cohort_count integer nullable
  • three_year_default_cohort_count integer nullable
  • windows array (default: [])
    • @type string (default: "CollegescorecardRepaymentWindow")
    • years integer nullable
    • repayment_rate number nullable
    • borrower_count integer nullable
• admissions object nullable
  • @type string (default: "CollegescorecardAdmissions")
  • admission_rate number nullable
  • admission_rate_overall number nullable
  • admission_rate_by_ope_id number nullable
  • test_requirements_code string nullable
  • sat_average number nullable
  • sat_reading_25th integer nullable
  • sat_reading_50th integer nullable
  • sat_reading_75th integer nullable
  • sat_math_25th integer nullable
  • sat_math_50th integer nullable
  • sat_math_75th integer nullable
  • sat_writing_25th integer nullable
  • sat_writing_50th integer nullable
  • sat_writing_75th integer nullable
  • act_cumulative_25th integer nullable
  • act_cumulative_50th integer nullable
  • act_cumulative_75th integer nullable
  • act_english_25th integer nullable
  • act_english_50th integer nullable
  • act_english_75th integer nullable
  • act_math_25th integer nullable
  • act_math_50th integer nullable
  • act_math_75th integer nullable
  • act_writing_25th integer nullable
  • act_writing_75th integer nullable
• academics object nullable
  • @type string (default: "CollegescorecardAcademics")
  • offers_certificate boolean nullable
  • offers_associate boolean nullable
  • offers_bachelors boolean nullable
  • reported_program_count integer nullable
  • programs array (default: [])
    • @type string (default: "CollegescorecardProgram")
    • field_of_study string nullable
    • degrees_awarded_percent number nullable
    • offers_certificate_under_1_year boolean nullable
    • offers_certificate_1_to_2_years boolean nullable
    • offers_certificate_2_to_4_years boolean nullable
    • offers_associate boolean nullable
    • offers_bachelors boolean nullable
    • offers_degree boolean nullable
  • reported_programs array (default: [])
    • @type string (default: "CollegescorecardReportedProgram")
    • cip_code string nullable
    • program_title string nullable
    • months_to_completion number nullable
    • annualized_cost number nullable
    • full_program_cost number nullable

Errors

• 422 — 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 — The entity was not found, or a precondition failed 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.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-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.