Widget

Live demo

This is the widget, embedded on this page with the snippet below. Try any US address. To see it on a city site, open the demo city website: a full Planning & Zoning page with the widget installed in the city’s colours.

Install

1. 1

   Get a key

   A city or county gets its key from its city account. A city email address is verified at once; otherwise we confirm the account by hand first, and the widget stays paused until then. A company serving several cities applies to the partner program and turns each city on from one console.

2. 2

   Allow your domains

   The key lists the exact origins allowed to show the widget, such as https://www.yourcity.gov. Add staging and production.

3. 3

   Paste the snippet

   Put it where the checker should appear. The script is optional: it fits the iframe’s height to its content. Without it, keep the fixed 560px height, which fits every state.

   <iframe data-buildability
     src="https://buildability.us/embed/checker?key=YOUR_KEY&city=Austin&state=TX"
     style="width:100%;border:0;height:560px"
     title="Buildability checker" allow="payment"></iframe>
   <!-- optional: fits the height -->
   <script src="https://buildability.us/embed.js" async></script>

Parameters

Everything is a query parameter on the iframe src.

https://buildability.us/embed/checker
  ?key=YOUR_KEY      your partner key
  &city=Austin       the city residents are in
  &state=TX          two-letter state
  &accent=0b5cab     your brand colour, hex
  &lang=es           Spanish (or en)

Keys and origins

• Origin allow-list. The widget is served with a frame-ancestors policy naming your key’s origins. A copied snippet on any other site won’t render. Without a valid key it renders only on buildability.us.
• One quota per key. All traffic through your key shares one quota, across every page and visitor. Over quota, residents see “busy, try again in a minute”, not an error.
• Paused is paused. A paused partner, or a city account not yet verified, gets the same treatment as no key.

What residents see

• An address box with suggestions, and project chips: ADU, addition, garage or shed, fence, new home, split lot.
• The Score, grade and a plain answer (“Likely yes”, “Maybe”, “Hard to build here”) with the sentence behind it, on the canonical score colours.
• An answer for their project, and your city’s own next-step links and contact, set in the Partner Console.
• “Powered by Buildability”. Co-branding is part of the deal.

A first lookup takes about 20 seconds while the sources answer, and the widget narrates them. Repeat lookups are instant.

Payment

Before payment, the widget shows the Score and two factors. A resident who wants the rest buys the full report for $99 without an account: checkout opens in a new tab, and the widget unlocks in place once payment goes through. The purchase lands on a claim page where the resident can attach it to an account. Keep allow="payment" on the iframe.

Events

The widget posts one message to its parent page, buildability:resize, with its content height in pixels. embed.js listens for it and sets the iframe’s height, clamped to 120–2000px. If you size the frame yourself, listen for it directly:

window.addEventListener('message', (e) => {
  if (e.origin !== 'https://buildability.us') return;
  if (e.data?.type === 'buildability:resize') {
    console.log('widget height', e.data.height);
  }
});

There are no result or purchase events. Results stay inside the frame.

Accessibility

Government sites have to be accessible, so the widget is built for procurement review:

• Full keyboard operation with visible focus.
• Progress announced in a live region while checking, the full result announced politely, and errors announced as alerts.
• AA contrast, including score colours used as text and any accent you set.
• Respects prefers-reduced-motion.