Documentation menu
Docs / Reference / New business openings

New business openings

GET/opening

Parameters

ParameterTypeDescription
municipalitystringoptionalFilter to one city by its slug, e.g. 'new_westminster', 'toronto', 'north_vancouver_city'.Exact match. The dataset's /coverage endpoint lists the valid slugs. 'city' is accepted as an alias.
statusstringoptionalPermits: the normalized status (issued, in_review, completed, expired, cancelled, unknown), same as status_canonical.Major projects: proposed, under_construction, complete, on_hold, cancelled. Business licences: the status the city publishes, e.g. APPROVED, case-insensitive. Other datasets: the status as the city publishes it.
categorystringoptionalMajor projects: the source's own sector wording, e.g. 'Transit'.Use sector for the canonical bucket, which spans both official languages.
qstringoptionalFull-text search across the indexed fields of the record, e.g. q=roofing or q="Iron Hill".Matches business, contractor and project names, the address, the city and the permit or licence number, on every plan including free. It does not match a person's name: these datasets carry business records only. Space-separated words require all terms ("deck addition"). Use OR to match any term ("pool OR spa"), quotes for an exact phrase ("secondary suite"), and a leading minus to exclude ("renovation -interior").
opened_fromstringoptionalEarliest opening date YYYY-MM-DD
opened_tostringoptionalLatest opening date YYYY-MM-DD
preceded_by_permitbooleanoptionalOnly businesses with a building permit at the same address
is_contractorbooleanoptionalOnly contractors
has_addressbooleanoptionalOnly businesses with a street address.Home-based sole proprietors have none, so set this when the address is the point.
sort_bystringoptionalSort field: date (the record's own date, e.g. issued_date for permits) or value (the field value_min reads).
sort_orderstringoptional
limitintegeroptional
offsetintegeroptional

Request

curl --request GET \
  --url 'https://api.builddata.ca/opening' \
  --header 'X-API-Key: YOUR_API_KEY'
import requests

url = "https://api.builddata.ca/opening"
headers = {"X-API-Key": "YOUR_API_KEY"}
resp = requests.get(url, headers=headers)
print(resp.json())
const res = await fetch("https://api.builddata.ca/opening", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
console.log(data);
<?php
$ch = curl_init("https://api.builddata.ca/opening");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: YOUR_API_KEY",
]);
echo curl_exec($ch);
require "net/http"
require "uri"

uri = URI("https://api.builddata.ca/opening")
req = Net::HTTP::Get.new(uri)
req["X-API-Key"] = "YOUR_API_KEY"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body
package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.builddata.ca/opening", nil)
    req.Header.Add("X-API-Key", "YOUR_API_KEY")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)
    fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.*;

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.builddata.ca/opening"))
    .header("X-API-Key", "YOUR_API_KEY")
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

Errors

Every error returns {"detail": "…"}, a sentence naming what was wrong and, where there is one, the fix, plus docs and, when they apply, did_you_mean (the nearest valid value) and valid (the accepted values).

StatusWhen
400The request is understood but cannot be served as asked, e.g. offset above 9500, or cursor combined with sort_by=value. The message names the fix.
403Missing or invalid API key; a route that needs a paid plan, called with a free key; or, on a free key, a record first seen inside the last 30 days, asked for by id. The message says which.
404No such endpoint, or no record with that id.
422A parameter is invalid: an unknown city slug, an impossible date, a limit above 500, an unrecognised sort field, or a misspelled parameter name. The message names the parameter and, where there is one, the nearest valid value.
429Rate limit or plan quota exceeded.
500Unexpected server error.
504The query took too long. Narrow it with a municipality or a date range.
Ready to build?Create a free key and start calling BuildData in minutes. No card required.
Get your API key →