Dartmouth API Developer Portal

Value Lists - Countries API

Returns information about known countries.

Rating

Attribute Value
Highly Available Yes
Cache Refresh Interval 4 hours
Filtering Yes

Required Scopes

None: value list APIs require only authentication to Dartmouth's login API as documented in the introduction section of this portal.

Request

GET /api/countries/{id}

Required Headers

Authorization: Bearer {jwt}

Parameters

Parameter Name Type Description Valid values Required

(standard filter parameters as documented in the introduction section of this portal)

Notes on usage

Value lists provide consistent information about objects referenced by multiple applications (e.g. states, countries, genders, student_types). All value list items include an "id" attribute and a "name" attribute. The "id" value is often included in other objects (e.g. the /students API includes a student_type_id attribute); this value can be used as the {id} parameter of the URL (e.g. /student_types/{id}) to get details of the value list item.

When {id} is excluded from the URL, the entire value list is returned as a collection. This can be useful when an application needs to provide a complete list of valid selections. Standard filtering via URL parameters is also available and returns a collection; the collection will be empty if no records are qualified by the filtering.

Returns

Status Code Description
200 {id} requested exists or was not specified
404 {id} requested does not exist

Sample Request

https://api.dartmouth.edu/api/countries/CZ

Sample Return

{
    "id": "CZ",
    "cache_date": "2019-07-19T16:12:02Z",
    "is_active": true,
    "name": "Czechoslovakia"
}