School Data API
ESD is tracking data about two different, but sometimes related, universes: schools and early childhood centers. Information is culled from many different sources: State of Michigan data exports, scraped data, ESD-collected surveys, and other nonprofits like Great Schools.
The data is keyed with both ESD identifiers -- we can guarantee these are unique -- as well as with potentially not-so-unique identifiers from other vendors. For example, the State of Michigan identifies schools by an identifier “Building Code” aka BCODE. It isn’t clear how unique this identifier is, so we use our own ID and then look up bcodes based on that to join against state datasets.
A similar problem exists with early childhood centers -- the State identifies them by their License Number, which is an alphanumeric string. It turns out that the alpha part of the string can be removed & it’s still unique as far as we can tell -- we use this to create an “esd_ec_id” early childhood center id… this way we can easily do JOINs against state databases. Just in case the State ends up re-issuing a license number, we still have an internal serial id for early childhood centers.
Say you want to get a list of all the authorizers.
You know that authorizers is one of the portal’s vocabularies, but you need to find its taxonomy ID so you can run related queries.
To list all the vocabularies, GET https://portal.excellentschoolsdetroit.org/api/1.0/taxonomy_vocabulary In that result, you find that Authorizer is vocabulary id 11.
Now that you have the vid, you can ask the API for all of its terms. You can POST some search parameters like ‘{"vid":"11","load_entities":"1"}’ to https://portal.excellentschoolsdetroit.org/api/1.0/taxonomy_vocabulary/getTree.json -- also provide the formatting you’re using for those parameters as a request header.
Example:
curl --data '{"vid":"11","load_entities":"1"}' --header 'Content-type: application/json' 'https://portal.excellentschoolsdetroit.org/api/1.0/taxonomy_vocabulary/getTree.json/' | python -mjson.tool | less
The current API base path is https://portal.excellentschoolsdetroit.org/api/1.0/
The default output format is XML. Other formats include bencode, json, jsonp, and serialized PHP (php). For example, add ".json/" as a suffix to receive JSON data.
Different types of data are available through different resources:
taxonomy_vocabulary
taxonomy_vocabulary/getTree
POST paramters:
- vid (vocabulary id as found in "list all vocabularies")
- load_entities (bool, whether or not to load additional fields)
Example: get all terms in "schools" vocabulary as JSON
curl -D - --data '{"vid":"4","load_entities":"1"}' --header 'Content-type: application/json' 'https://portal.excellentschoolsdetroit.org/api/1.0/taxonomy_vocabulary/getTree.json/'taxonomy_term/selectNodes
POST parameter: tid (term id as found in "List terms in a vocabulary")
Example: get content related to Aisha Shule/WEB Dubois Prep. Academy School as JSON
curl --data '{"tid":"2121"}' --header "Content-type: application/json" -D - 'https://portal.excellentschoolsdetroit.org/api/1.0/taxonomy_term/selectNodes.json'views/[view_id]
[view_id] is one of ESD's [public datasets](Public datasets), for example meap_2012
GET parameters:
- filters[bcode]=bcode (optional, return single record)
- limit=n (number of records to return)
- offset=n (offset from start)
Example: get records 11-20 of meap_2012 dataset as serialized PHP
curl 'https://portal.excellentschoolsdetroit.org/api/1.0/views/meap_2012.php/?limit=10&offset=1'Example: get a single school's data
curl -g 'https://portal.excellentschoolsdetroit.org/api/1.0/views/meap_2012.json/?filters[bcode]=4066'See https://portal.excellentschoolsdetroit.org/developers/schools for documentation on our new & improved API resources.
ESD's early childhood dataset catalogues early childhood centers (by name, location, state license number, and more). Each of these early childhood centers may also have additional sets of information associated with them, like the early childhood center profile generated by ESD.
The early childhood dataset is formatted using JSON API -- a standardized way to exchange structured data using JavaScript Object Notation (JSON). Read more at http://jsonapi.org/.
In JSON API format, our dataset becomes a collection of "resource objects," with each record for a unique early childhood center being a single "resource object." We can return the "root" of a resource object and it will contain, at minimum, an "id" and "type".
In the case of requesting records form api/1.0/ecs, every record returned in the data array will have a type of ecs (early childhood centers). Numerous IDs are included for each early childhood center - most notably, "field_esd_ec_id" is ESD's unique identifier for each center. Additionally, "tid" is its database id, "uuid" is generated arbitrarily each time the dataset is loaded and can be used to internally fetch information, and "field_state_license_id" is the unaltered State of Michigan license number.
We also know that each center in our dataset may have associated information, like a profile. JSON API lets us easily organize this additional information through "resource relationships," meaning that a resource object can be linked to another resource object.
An early childhood center and a school profile are both "resource objects," so they must have an "id" and "type." If you request a list of early childhood centers and choose to include each center's "profile", ec_profile, as in https://2015scorecard-3mhev6qb5ihtc.us.platform.sh/api/1.0/ecs.json?limit=5&offset=350&includes=ec_profile each early childhood center resource that has an ESD profile will include a linkage to an object in the included object. The linkage only specifies the school profile "id" and "type", while the included object contains numerous data fields to describe the ec_profile.
If you only request a list of early childhood centers, as in https://2015scorecard-3mhev6qb5ihtc.us.platform.sh/api/1.0/ecs.json?limit=5&offset=350 each early childhood center resource that has an ESD profile will still include a linkage with an "id" and "type", but not the more descriptive included object.