### API Request Example: Retrieve Specific Data Fields Source: https://collegescorecard.ed.gov/data/api/index An example of an API request that uses the `fields` parameter to retrieve a specific set of data points for schools, such as admission rates and student size. ```http https://api.data.gov/ed/collegescorecard/v1/schools?api_key=YOUR_API_KEY&fields=id,school.name,latest.admissions.admission_rate.overall,latest.student.size ``` -------------------------------- ### JSON Response Structure Example Source: https://collegescorecard.ed.gov/data/api/-documentation Illustrates the typical JSON structure returned by the API, including metadata and a list of results. This format is consistent for most successful data retrieval requests. ```json { "metadata": { "total": 1, "page": 0, "per_page": 20 }, "results": [ { "id": 166027, "school.name": "Harvard University", "latest.student.size": 31145 } ] } ``` -------------------------------- ### Search Schools by Name Source: https://collegescorecard.ed.gov/data/api/-documentation An example API request to find schools by their name. This demonstrates a basic filtering capability using a specific school name. ```http https://api.data.gov/ed/collegescorecard/v1/schools?api_key=YOUR_API_KEY&school.name=Stanford University ``` -------------------------------- ### Example Error Response Structure Source: https://collegescorecard.ed.gov/data/api/-documentation Demonstrates the JSON format for error responses, providing a 'code' and 'message' to help diagnose request failures. This structure is returned when API requests are unsuccessful. ```json { "error": { "code": 400, "message": "Invalid request parameters" } } ``` -------------------------------- ### Paginated API Request Source: https://collegescorecard.ed.gov/data/api/-documentation An example of how to implement pagination in API requests, specifying the page number and the number of results per page. This is essential for handling large datasets. ```http https://api.data.gov/ed/collegescorecard/v1/schools?api_key=YOUR_API_KEY&school.state=TX&page=2&per_page=10 ``` -------------------------------- ### API Request with Field Selection Source: https://collegescorecard.ed.gov/data/api/-documentation Shows how to construct a URL to query the API, specifying desired data fields using the 'fields' parameter. This helps to reduce response size and improve parsing efficiency. ```http https://api.data.gov/ed/collegescorecard/v1/schools?api_key=YOUR_API_KEY&fields=id,school.name,latest.cost.tuition.in_state,latest.completion.rate ``` -------------------------------- ### Filter by Value List Source: https://collegescorecard.ed.gov/data/api/-documentation Explains and demonstrates how to filter results based on a comma-separated list of acceptable values for a given field. This is useful for matching multiple discrete options. ```http school.degrees_awarded.predominant=2,3,4 ``` -------------------------------- ### Range Match Filter Source: https://collegescorecard.ed.gov/data/api/-documentation Demonstrates how to filter records based on a numeric range using the `__range` operator. This allows for queries within a specified minimum and maximum value, including open-ended ranges. ```http 2013.student.size__range=100..500 ``` ```http 2013.student.size__range=1000.. ``` -------------------------------- ### Rate Limits Source: https://collegescorecard.ed.gov/data/api/-documentation Information on API rate limits, including the default limit and how to request an increase. ```APIDOC ## Rate Limits ### Description The API enforces rate limiting to ensure fair usage. If you exceed the allowed number of requests, you will receive a `429 Too Many Requests` response. ### Details - **Default Rate Limit**: 1,000 requests per IP address per hour. ### Requesting an Increase If you are encountering rate limit issues, please contact scorecarddata@rti.org to request an increase. ``` -------------------------------- ### Filter Schools by State and City Source: https://collegescorecard.ed.gov/data/api/-documentation Illustrates how to filter school search results by both state and city parameters. This allows for more precise location-based queries. ```http https://api.data.gov/ed/collegescorecard/v1/schools?api_key=YOUR_API_KEY&school.state=NY&school.city=New York ``` -------------------------------- ### Retrieve Specific Data Fields Source: https://collegescorecard.ed.gov/data/api/-documentation Demonstrates a request to retrieve only specific data fields for schools, such as ID, name, admission rate, and student size. This is useful for targeted data analysis. ```http https://api.data.gov/ed/collegescorecard/v1/schools?api_key=YOUR_API_KEY&fields=id,school.name,latest.admissions.admission_rate.overall,latest.student.size ``` -------------------------------- ### Negative Match Filter Source: https://collegescorecard.ed.gov/data/api/-documentation Shows how to exclude records that match a specific value using the `__not` operator. This is helpful for refining search results by exclusion. ```http school.region_id__not=5 ``` -------------------------------- ### Nesting Field of Study Results Source: https://collegescorecard.ed.gov/data/api/-documentation Manage the nesting of field of study results. By default, only matching program objects are returned. Use `all_programs_nested=true` to return all program objects within the array. ```APIDOC ## Nesting Field of Study Results ### Description Manage the nesting of field of study results. By default, only matching program objects are returned. Use `all_programs_nested=true` to return all program objects within the array. ### Method GET ### Endpoint /websites/collegescorecard_ed_gov_data_api ### Query Parameters - **all_programs_nested** (boolean) - Optional - If set to `true`, returns all items in the field of study array, not just those matching search parameters. ### Request Example ``` /websites/collegescorecard_ed_gov_data_api?search_parameter=Computer Science&all_programs_nested=true ``` ### Response #### Success Response (200) - **[field_of_study_key]** (array) - An array of field of study objects. #### Response Example ```json { "programs": [ { "title": "Computer Science", "completion_rate": 0.6 }, { "title": "Software Engineering", "completion_rate": 0.7 } ] } ``` ``` -------------------------------- ### Managing Nested Field of Study Results Source: https://collegescorecard.ed.gov/data/api/index Control the return of nested field of study data. By default, only matching objects in the array are returned. Use `all_programs_nested=true` to return all items in the array. ```HTTP GET /api/v1/schools/?fieldofstudy=Computer%20Science ``` ```HTTP GET /api/v1/schools/?fieldofstudy=Computer%20Science&all_programs_nested=true ``` -------------------------------- ### Nesting Field of Study Results Source: https://collegescorecard.ed.gov/data/api/-documentation Control the return of nested field of study data. By default, only matching objects within the array are returned. Setting `all_programs_nested=true` returns all items in the array, regardless of whether they match the search parameter. ```text &all_programs_nested=true ``` -------------------------------- ### Schools Search API Source: https://collegescorecard.ed.gov/data/api/-documentation This endpoint allows you to search for schools based on various criteria such as name, state, and city. You can also specify which fields to return and control pagination. ```APIDOC ## GET /schools ### Description Searches for schools based on specified criteria and returns relevant data. ### Method GET ### Endpoint https://api.data.gov/ed/collegescorecard/v1/schools ### Parameters #### Query Parameters - **api_key** (string) - Required - Your API key. - **school.name** (string) - Optional - Filters schools by name. - **school.state** (string) - Optional - Filters schools by state. - **school.city** (string) - Optional - Filters schools by city. - **fields** (string) - Optional - Comma-separated list of fields to include in the response. Supports wildcard fields. - **keys_nested** (boolean) - Optional - If true, returns nested JSON objects instead of dotted strings for fields. - **page** (integer) - Optional - The page number for paginated results. - **per_page** (integer) - Optional - The number of results per page. - **school.degrees_awarded.predominant** (string) - Optional - Filters by predominant degrees awarded (e.g., '2,3,4'). - **school.region_id__not** (integer) - Optional - Excludes schools from a specific region ID. - **[year].student.size__range** (string) - Optional - Filters schools by student size range for a specific year (e.g., '1000..5000'). ### Request Example ``` https://api.data.gov/ed/collegescorecard/v1/schools?api_key=YOUR_API_KEY&school.name=Stanford University&fields=id,school.name,latest.admissions.admission_rate.overall ``` ### Response #### Success Response (200) - **metadata** (object) - Contains pagination information (total, page, per_page). - **results** (array) - An array of school objects, each containing the requested fields. #### Response Example ```json { "metadata": { "total": 1, "page": 0, "per_page": 20 }, "results": [ { "id": 166027, "school.name": "Harvard University", "latest.student.size": 31145 } ] } ``` #### Error Response - **error** (object) - Contains error details (code, message). #### Error Response Example ```json { "error": { "code": 400, "message": "Invalid request parameters" } } ``` ``` -------------------------------- ### Geographic Filtering with Zip and Distance Parameters Source: https://collegescorecard.ed.gov/data/api/-documentation Filter API results to include only those within a specified geographic area. The `zip` parameter takes a U.S. zip code, and the `distance` parameter specifies the radius in miles (default) or kilometers. Distances are calculated from the center of the zip code. ```text zip=12345&distance=10mi ``` ```text zip=90210&distance=50km ``` -------------------------------- ### Schools API Endpoint Source: https://collegescorecard.ed.gov/data/api/-documentation Retrieve information about U.S. higher education institutions using various filtering and sorting parameters. ```APIDOC ## GET /schools ### Description Retrieves a list of U.S. higher education institutions based on specified criteria. Supports filtering by school name, state, city, and allows for custom field selection, pagination, and sorting. ### Method GET ### Endpoint https://api.data.gov/ed/collegescorecard/v1/schools ### Parameters #### Query Parameters - **api_key** (string) - Required - Your unique API key for authentication. - **school.name** (string) - Optional - Filters results by the school's name. Example: `school.name=Harvard University`. - **school.state** (string) - Optional - Filters results by the school's state. Example: `school.state=CA`. - **school.city** (string) - Optional - Filters results by the school's city. Example: `school.city=Boston`. - **fields** (string) - Optional - Specifies which fields to include in the response. Example: `fields=id,school.name,latest.student.size`. - **page** (integer) - Optional - Specifies the page number for pagination. Default is 0. - **per_page** (integer) - Optional - Specifies the number of results per page. Default is 20, maximum is 100. - **sort** (string) - Optional - Sorts results by a given field. Can be ascending (`:asc`) or descending (`:desc`). Example: `sort=latest.student.size:desc`. ### Request Example ``` https://api.data.gov/ed/collegescorecard/v1/schools?api_key=YOUR_API_KEY&school.name=Harvard University&fields=id,school.name,latest.student.size ``` ### Response #### Success Response (200) - **id** (integer) - Unique identifier for the institution. - **school.name** (string) - The name of the school. - **latest.student.size** (integer) - The latest reported student enrollment size. #### Response Example ```json { "metadata": { "page": 0, "per_page": 20, "record_count": 100, "total_record_count": 5000 }, "results": [ { "id": 186074, "school.name": "Harvard University", "latest.student.size": 21774 } ] } ``` ``` -------------------------------- ### Geographic Filtering Source: https://collegescorecard.ed.gov/data/api/-documentation Filter search results based on geographic location using zip code and distance parameters. Supports miles and kilometers, and calculates distance from the center of the zip code. ```APIDOC ## Geographic Filtering ### Description Filter search results based on geographic location using zip code and distance parameters. Supports miles and kilometers, and calculates distance from the center of the zip code. ### Method GET ### Endpoint /websites/collegescorecard_ed_gov_data_api ### Query Parameters - **zip** (string) - Required - The zip code to center the search around. - **distance** (string) - Required - The distance from the zip code. Can be specified in miles (e.g., '10mi') or kilometers (e.g., '20km'). Defaults to miles if no unit is specified. ### Request Example ``` /websites/collegescorecard_ed_gov_data_api?zip=12345&distance=10mi ``` ### Response #### Success Response (200) - **location.lat** (number) - Latitude of the record. - **location.lon** (number) - Longitude of the record. #### Response Example ```json { "location": { "lat": 34.0522, "lon": -118.2437 } } ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.