Schools Canada
Description
Schools near a location can be accessed via Local Logic’s Schools endpoint, documented below. Schools will always be returned in order of least to greatest linear_distance
away from the specified lat/lng.
Data Dictionary
The following is a table that contains payload fields and describes their meaning and possible values.
field | description | values | format |
---|---|---|---|
name | The name of the school. | Max string length: 107 Average string length: 28 | String |
url | The website of the school. | Max string length: 113 Average string length: 33 | String |
school_attributes.levels | The levels of education offered by the school. It will depend on each individual school board, but generally, each level roughly corresponds with the following grade ranges: | preschool elementary middle secondary | A list of strings from the values column. Ex: ['elementary', ‘secondary’] |
school_attributes.grades | The grades offered by the school. | Different range combinations: PK : pre-kindergarten JK : junior kindergarten SK : senior kindergarten N : nursery M : maternelle | A string containing a grade range from the values column, separated by a dash. Ex: JK-8 |
school_attributes.languages | The languages of instruction. | Non-exhaustive list: en : English fr : French ar : Arabic cr : Cree | A list of strings from the values column. Ex: ['en', 'fr'] |
school_attributes.programs | The programs offered by the school. | Non-exhaustive list: Max sum of string lengths: 100 Average sum of string lengths: 17 | A list of strings from the values column. Ex: ['IB', ‘Arts’] |
school_attributes.types | The type of the school. | public private | A list of strings from the values column. Ex: ['public'] |
school_board_attributes.name | The name of the school board. | Max string length: 73 Average string length: 24 | String |
school_board_attributes.url | The website of the school board. | Max string length: 50 Average string length: 22 | String |
proximity.walking.distance | The distance in meters between the school and the input lat/lng. | Integer | |
proximity.walking.time | The time it takes in minutes to travel between the school and the input lat/lng. | Integer | |
catchments.*.geometry | A lat/lng multipolygon of the catchment area. | List | |
catchments.*.inside | Whether or not the queried lat/lng fall inside the catchment. | Bool | |
catchments.*.program | The program offered to this catchment. | String | |
catchments.*.grade | The grade offered to this catchment. Refer to school_attributes.grades for more information. | String | |
catchments.*.level | The level offered to this catchment. Refer to school_attributes.levels for more information. | String |
GET v3/schools
Up to 30 elementary schools and 30 high schools in a 25 000 meter (25 km or 15.53 miles) radius can be obtained through the API.
proximity.walking
data, including walking distance
and walking travel_time
is currently only available for the 5 closest schools. The quality
value represents whether the data is calculated
or estimated
.
Keys under school_attributes
and school_board_attributes
may not always be present, depending on the richness of our dataset.
GET v3/schools
Header
This API uses JWT token based authentication. This JWT Bearer token is what is used to populate the
Authorization
header below.
Instructions on how to retrieve this token can be found at Getting Started.
Header | Status | Description |
---|---|---|
Authorization | required | Your bearer token retrieved from our authorization API, ex. Bearer eyJhbGci... |
Accept | required | The datatype to request, this API will return application/json . |
QueryString
The region to be queried by the endpoint can be defined two ways: (1) by specifying a lat
/lng
coordinate, with optional radius
/radius_unit
parameters, (2) or by providing a polygon
parameter.
When using the lat
/lng
coordinate query method without specifying radius
/radius_unit
parameters, the endpoint will return schools within a five minute walk of the coordinate.
When including radius
/radius_unit
parameters, the resulting circular area around the lat
/lng
coordinate will be queried. radius_unit
can be either meter
or mile
.
When using the polygon
query method, the schools returned will be within the region defined by the polygon area. Polygons are specified using the WKT format.
The only accepted type is POLYGON
, and holes are not supported. Each polygon point must be defined as a lng
/lat
coordinate.
API Limitations
- The polygon query string has been limited to 5000 chars.
- The max north/south east/west distance accepted is 0.5 degrees.
- The max count of north/south east/west level 6 geohashes is 1000.
WKT works on x/y planes. Therefore, the coordinates must be sent as lng
/lat
instead of lat
/lng
.
Parameter | Status | Description |
---|---|---|
lat | optional | A decimal number between -90 and 90 , representing the latitude.() |
lng | optional | A decimal number between -180 and 180 , representing the longitude. |
polygon | optional | List of 2D lng/lat points that define a 2D polygon, using the WKT representation |
radius | optional | Used to specify the maximum distance (in meters) away from the input lat/lng. default: 5 000 meters maximum: 25 000 meters |
limit | optional | The limit of schools returned. default: 30 maximum: 30 |
language | optional | String value representing the two letter ISO 361-1 language code to return the payload in, ex. fr Available: en and fr default: en * translations only available for the following fields:
|
include_catchments | optional | Defaults to false . A boolean to get the school attendance catchments area or not. If true , the response will contain a catchments key that will contain the list of catchments. It may be an empty list when the catchments information is unavailable, which is the case for private schools and some public schools. The catchments key will not be defined if include_catchments is false . |
Usage examples
- NodeJS
- Python
require('node-fetch')('https://api.locallogic.co/v3/schools?' + new URLSearchParams({
lat: 43.892958,
lng: -79.426238,
radius: 3000,
limit: 10,
include_catchments: true
}), {
method: 'GET',
headers: {
Accept: 'application/json',
Authorization: 'Bearer eyJhbGciOiJ...'
}
})
.then(response => response.json())
.then(body => {
console.log(body)
})
.catch(error => {
console.log(error)
})
import requests
response = requests.get(
"https://api.locallogic.co/v3/schools",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."},
params={
"lat": 43.892958,
"lng": -79.426238,
"radius": 3000,
"limit": 10,
"include_catchments": True
}
)
print(response.json())
Response example
{
"data": {
"primary_schools": [
{
"name": "Beverley Acres Public School",
"address": "283 Neal Dr",
"city": "Richmond Hill",
"province": "ON",
"postalcode": "L4C 3L3",
"country": "Canada",
"lat": 43.889188,
"lng": -79.423505,
"url": "http://beverleyacres.ps.yrdsb.ca",
"school_attributes": {
"levels": ["elementary"],
"grades": "1-8",
"languages": ["en", "fr"],
"types": ["public"],
"programs": ["French Immersion"]
},
"school_board_attributes": {
"name": "York Region District School Board",
"url": "http://www.yrdsb.ca"
},
"proximity": {
"linear_distance": 0,
"walking": {
"quality": "calculated",
"distance": 87,
"travel_time": 1
}
}
"catchments": [
{
"geometry": [[[[43.91933, -79.38866], [43.91067, -79.38655], ...]]]
"inside": true,
"program": "french immersion",
"grades": "4-8",
"level": "elementary"
}
]
}
// Plus other primary_schools
],
"high_schools": [
{
"name": "TMS School - Elgin Mills",
"address": "500 Elgin Mills Road E",
"city": "Richmond Hill",
"province": "ON",
"postalcode": "L4C 5G1",
"country": "Canada",
"lat": 43.892958,
"lng": -79.426238,
"url": "http://www.tmsschool.ca",
"school_attributes": {
"levels": ["elementary", "secondary"],
"types": ["private"]
},
"proximity": {
"linear_distance": 472,
"walking": {
"quality": "calculated",
"distance": 472,
"travel_time": 5
}
},
"catchments": []
}
// Plus other high_schools
]
},
"meta": {
"message": "Successfully called v3/schools API.",
"type": "LocalLogic.API.Success",
"statusCode": 200,
"counts": {
"primary_schools": 30,
"high_schools": 24
}
}
}
SDK Implementations
Schools is used by two Local Logic SDKs:
SDK | Description |
---|---|
Local Schools SDK | Retrieves the schools and their catchment areas for displaying on the SDK map. |
Local Content SDK | Retrieves the schools and their catchment areas for displaying on the SDK map. |
NeighborhoodMap SDK | Retrieves the schools within and close to the neighborhood. |
Error codes
When calling Local Logic’s API, you may receive an HTTP error code. These errors are explained below. In general, error codes starting with “4” are due to an invalid API call and can be fixed on your end, whereas error codes starting with “5” are due to server errors (that is, problems on our end). If you receive something not described here, please contact us at support@locallogic.co.
400 - BadRequest
This error code happens when the request inputs are incorrect. Use the detail field of the response for clarification. Example:
{
"code": "LocalLogic.API.BadRequest",
"detail": "ValidationErrors: AroundEndpoint is invalid:\n\tinclude is invalid: \"bad_input\" is not an acceptable value: \"groceries\", \"restaurants\", \"nightlife\", \"cafes\", \"shopping\", \"daycares\", \"primary_schools\", \"high_schools\""
}
401 - Unauthorized
This error code happens when your API key cannot access specific resources or locations. For example, some API keys can only access certain countries / states / provinces. Feel free to contact us for more information. Example:
{
"code": "LocalLogic.API.Unauthorized",
"detail": "Your API KEY doesn't support this region"
}
403 - Forbidden
This error code happens when you forgot to include security credentials with your request or you are requesting a parameter that you do not have access to. Example:
{
"message": "Forbidden"
}
404 - NotFound
This error code happens when we don’t have data for the requested location. For example, if you send a lat/lng pair for a location in Antarctica, we will return this error as we don’t have data for Antarctica (yet!). Example:
{
"code": "LocalLogic.API.NotFound",
"detail": "No Location Scores found for this location."
}
422 - Unprocessable Entity
This error code is returned when the correct parameters have been sent however, the data they contain is not valid. For example, if you send a lat/lng pair and the latitude is invalid (ie. not in the range [-90, 90]) and/or the longitude is invalid (ie. not in the range [-180, 180]).
{
"message": "Latitude must be within [-90, 90], Longitude must be within [-180, 180], Requires at least lat/lng pair, or geography_ids. None supplied.",
"code": "LocalLogic.API.BadRequest",
"statusCode": 422
}
500 - ServerError
This error code means that an error occurred on our end. Feel free to retry the same request to see if the problem persists. If you received a lot of these errors, please contact us at support@locallogic.co Example:
{
"code": "LocalLogic.API.ServerError",
"detail": "No Location Scores found for this location."
}
502 - BadGateway
This error code means that an error came from our cloud provider. Feel free to retry the same request to see if the problem persists. Example:
{
"message": "Internal server error"
}