Data API guide

School directory endpoints

School search is separate from nearby places. Directory mode accepts an optional trimmed q (up to 100 characters), one Canadian region,limit 1–20. Anonymous directory reads are limited to the first 200 matches, so offset + limit must be at most 200; keyed reads acceptoffset 0–10,000. Add paired finitelatitude, longitude, and a positive radius_kmup to 5 for an explicit nearby query. Nearby results only include source-published coordinates; directory results can include unmapped records. Directory reads are bounded at 20,000 records; offset remains capped at 10,000 andhas_more reflects that bound. A temporary school-catalog failure is reported as 503 rather than silently truncating the directory.

curl --fail-with-body --get "https://api.urlq.com/api/public/data/schools" \
  --data-urlencode "q=elementary" \
  --data-urlencode "region=BC" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

curl --fail-with-body --get "https://api.urlq.com/api/public/data/schools" \
  --data-urlencode "latitude=49.2827" \
  --data-urlencode "longitude=-123.1207" \
  --data-urlencode "radius_km=5" \
  --data-urlencode "limit=20"

SCHOOL_SEARCH_RESPONSE="$(curl --fail-with-body --get "https://api.urlq.com/api/public/data/schools" \
  --data-urlencode "q=elementary" \
  --data-urlencode "region=BC" \
  --data-urlencode "limit=20")"
SCHOOL_ID="$(printf '%s' "$SCHOOL_SEARCH_RESPONSE" | python3 -c 'import json,sys; print(json.load(sys.stdin)["items"][0]["id"])')"
curl --fail-with-body "https://api.urlq.com/api/public/data/schools/$SCHOOL_ID"

curl --fail-with-body "https://api.urlq.com/api/public/data/schools/coverage"

Existing workspace-key examples

curl --fail-with-body --get \
  -H "Authorization: Bearer $URLQ_API_KEY" \
  "https://api.urlq.com/api/v1/data/schools" \
  --data-urlencode "q=elementary" \
  --data-urlencode "region=BC" \
  --data-urlencode "limit=20"

SCHOOL_SEARCH_RESPONSE="$(curl --fail-with-body --get \
  -H "Authorization: Bearer $URLQ_API_KEY" \
  "https://api.urlq.com/api/v1/data/schools" \
  --data-urlencode "q=elementary" \
  --data-urlencode "region=BC" \
  --data-urlencode "limit=20")"
SCHOOL_ID="$(printf '%s' "$SCHOOL_SEARCH_RESPONSE" | python3 -c 'import json,sys; print(json.load(sys.stdin)["items"][0]["id"])')"
curl --fail-with-body \
  -H "Authorization: Bearer $URLQ_API_KEY" \
  "https://api.urlq.com/api/v1/data/schools/$SCHOOL_ID"

Search returns query, count, total, has_more, items, caveat, and coverage_url. Use /api/public/data/schools/coverage for region and source counts, and copy an item's opaque id to /api/public/data/schools/<id> for detail. School records describe directory facts only; they do not establish assignment, catchment, ranking, or enrolment eligibility. The school directory includes the live search controls.

Public endpoints

These routes require no key. The URLQ atlas calls them through its same-origin proxy; external callers can use curl or another server-side client. The detail example derives an opaque id from the first search item. Treat that public catalog handle as opaque and copy it unchanged between requests; it is not a secret.

curl --fail-with-body --get "https://api.urlq.com/api/public/data/places" \
  --data-urlencode "latitude=49.2827" \
  --data-urlencode "longitude=-123.1207" \
  --data-urlencode "radius_km=5" \
  --data-urlencode "category=park" \
  --data-urlencode "limit=20"

SEARCH_RESPONSE="$(curl --fail-with-body --get "https://api.urlq.com/api/public/data/places" \
  --data-urlencode "latitude=49.2827" \
  --data-urlencode "longitude=-123.1207" \
  --data-urlencode "radius_km=5" \
  --data-urlencode "category=park" \
  --data-urlencode "limit=20")"
PLACE_ID="$(printf '%s' "$SEARCH_RESPONSE" | python3 -c 'import json,sys; print(json.load(sys.stdin)["items"][0]["id"])')"
curl --fail-with-body "https://api.urlq.com/api/public/data/places/$PLACE_ID"

A category filter is applied before selection. Without one, the API takes at most five selected entries per category before applying the overall 20-item limit; a filtered query can return up to 20 entries from that category. Results are then ordered by distance and the list is not exhaustive.

Server-side workspace routes

Existing workspace API keys can call the matching /api/v1/data/places routes. Keep the key on your server as a workspace secret; never embed it in a browser bundle or publish it as a demo token.

curl --fail-with-body --get \
  -H "Authorization: Bearer $URLQ_API_KEY" \
  "https://api.urlq.com/api/v1/data/places" \
  --data-urlencode "latitude=49.2827" \
  --data-urlencode "longitude=-123.1207" \
  --data-urlencode "radius_km=5" \
  --data-urlencode "limit=20"

SEARCH_RESPONSE="$(curl --fail-with-body --get \
  -H "Authorization: Bearer $URLQ_API_KEY" \
  "https://api.urlq.com/api/v1/data/places" \
  --data-urlencode "latitude=49.2827" \
  --data-urlencode "longitude=-123.1207" \
  --data-urlencode "radius_km=5" \
  --data-urlencode "limit=20")"
PLACE_ID="$(printf '%s' "$SEARCH_RESPONSE" | python3 -c 'import json,sys; print(json.load(sys.stdin)["items"][0]["id"])')"
curl --fail-with-body \
  -H "Authorization: Bearer $URLQ_API_KEY" \
  "https://api.urlq.com/api/v1/data/places/$PLACE_ID"

Create and revoke keys from Admin integrations. Existing key permissions and integration controls continue to apply.

Query contract

Admitted categories are community, grocery, healthcare, library, park, pharmacy, playground, rapid_transit, recreation, shopping, trail, transit. rapid_transit is admitted by the API but may have zero records in the current snapshot; see the coverage page.

Response fields and provenance

Search returns release_id, query, count, items, selection_method, caveat, sources_url, and license_notices_url. Each item contains id, name, category, region, latitude, longitude, distance_km, distance_method, source_id, source_name, source_reference, source_as_of, license_url, and attribution.

Detail returns the same public item without distance fields, plus source metadata: source_id, name, reference, license_url, attribution, release, as_of, retrieved_at, and the source's complete admitted additional_notices entries. Each notice has a reference, licence URL, and attribution. Coordinates are representative dataset points, not verified facility entrances.

School items add source-backed name, region, optional address and authority fields, published grades, school website when supplied by the source, observed_at, optional source_updated_at, source links, attribution, and optionaldistance_km/distance_method for nearby queries. Missing optional fields remain absent; no address, grade, website, or coordinate is inferred.

Limits and errors

• Anonymous places, schools, coverage, and detail requests share 30 requests per visitor per minute, 200 per hour, and 500 per day.
• Keyed places, schools, coverage, and detail requests allow 60 requests per minute per key, with 1,200 per hour and 5,000 per day pooled across keys in the workspace.
• A shared data-catalog budget allows 600 places, schools, coverage, and detail requests per minute across callers.
• Nearby-place candidate work is capped at 10,000 rows. A dense places query returns 422; reduce the radius or add a category instead of receiving a silently truncated result. School directory reads have a separate 20,000-row bound and report 503 when the accepted catalog is unavailable.
• 429 responses include Retry-After. There is no bulk download or offline export in this beta.

Keep reading

See the live atlas, coverage acknowledgements, and the licence text made available with the selected public data.