Knowledge Base

Gryd API Usage Model

Overview

The Gryd API Usage Model explains how the API is used, which activity is free, which is billable, and how the pieces fit together.

Matching is free. You submit your data and Gryd matches it against its records at no charge, so you can explore coverage before you spend anything. Gryd bills when it delivers proprietary data: permit records, contractor details, licenses, contacts, system age, and jurisdiction data.

Paid endpoints are always billed, whether or not the area is covered. To help you decide, Gryd offers a free Coverage API that returns a ready-made coverage verdict and the measures behind it. Using it is optional, and you decide whether the answer changes your mind about making the paid call.

Every paid endpoint has its own price. A call to one endpoint does not cost the same as a call to another, because each returns different data with different value. Rates are set endpoint by endpoint. This article covers how the API is used and what is billable, not the rates themselves. For plan pricing, see Pricing. For an introduction to the API itself, see Intro to Gryd by BuildZoom API.

Key terminology

These six terms describe how software talks to the API. The API client runs in the customer's infrastructure, and Gryd's endpoints run in Gryd's. An API client sends a request and Gryd sends back a response. Only a request that Gryd completes successfully counts as a call, and whether that call is billed depends on the endpoint.

API terms

Term Definition
API client The software a customer uses to send API requests to our endpoints. The customer owns it and runs it in the customer's own infrastructure, not ours. The customer is the business that pays. The API client is the system acting on its behalf.
Endpoint A single API address an API client calls to ask us for something, such as GET /property_search. Each endpoint does one job. We group endpoints into types, such as lookup endpoints and paid endpoints.
API request A single message an API client sends to an endpoint to ask for something, such as one request to Building permits.
API response What we send back to the API client in answer to an API request, such as matched IDs, a coverage result, a page of up to 250 (TBC) permits, or an error. Every request gets a response.
Call A request we complete successfully. An error response, such as a server error (HTTP 500) or a client error (HTTP 4xx), doesn't count as a call and is never billed. Calls are the unit we bill on, but not every call is billable. Calls to paid endpoints are billed. Calls to lookup endpoints and to the Coverage API are free.
Rate limit A cap on how many requests an API client can send in a given period. All free APIs have one. An API client that goes over the limit receives an HTTP 429 response. That's an error response, so it isn't a call and isn't billed.

Product terms

Term Definition
Lookup endpoint A type of endpoint that matches a customer's data, such as addresses or contractor names, to the records we hold. This is what we mean by "matching", and it's always free. "Lookup" is short for "lookup endpoint". It always refers to this type of endpoint, never to a general action. There are two: Property Search and Contractor Search. They return matched IDs only, with no proprietary data. They're free because matching creates no standalone value. It's the gateway to paid data, and it lets customers explore our coverage at no cost.
Match ID An ID a lookup endpoint returns: a property ID, a contractor ID, or a permit jurisdiction ID (planned). Customers use these IDs to call other endpoints, such as paid endpoints and the Coverage API.
Coverage Whether we hold good permit data for an area. It's measured per permit jurisdiction by comparing our permit counts with Census survey counts. See the Coverage section.
Permit jurisdiction A city, township, or county that issues building permits. Each has a permit jurisdiction ID, which identifies it in the Coverage API and the jurisdiction data endpoints.
Coverage API A free part of the Gryd API, separate from the lookup endpoints, that returns coverage measures and a ready-made coverage verdict for a permit jurisdiction. Using it is optional. The customer decides whether coverage matters for their use case and whether to go ahead with a paid call.
Coverage verdict A ready-made answer to whether a permit jurisdiction is covered, returned by the Coverage API alongside the measures behind it. The interpretation comes from the analytics team. Customers can use it as is, or build their own rule from the measures.
Proprietary data What we charge for: permits, licenses, contacts, system age, and jurisdiction data.
Paid endpoint A type of endpoint that returns proprietary data. Always billed per call, whether or not the area is covered.
Jurisdiction data Paid, jurisdiction-level data such as geography, demographics, and permit statistics. Different from the free Coverage API, which only says whether an area is covered. Scope is still to be decided.
Permit page Permit endpoints return up to 250 (TBC) permits per page. Each page is a separate call, billed separately.
What is billable

The flow below follows a customer from the lookup endpoints to a paid call.

Usage rules and billing logic

Gryd bills on calls. The rules are:

  • Matching is free. Lookup endpoints and the Coverage API are never billed.
  • Paid endpoints are always billed per call, whether or not the area is covered.
  • Checking coverage first is the customer's choice. See How to Measure Coverage for how to use coverage information to fit your use case.
    • Permit endpoints return up to 250 (TBC) permits per page. Each page is a separate call, billed separately.
  • A paid call that returns no records is still a call, and it is billed.
  • Error responses, whether server errors (5xx) or client errors (4xx), are not calls and are not billed.
  • If a lookup endpoint finds no match, there is no paid call to make, so nothing is billed.
  • Free APIs are rate limited. See Rate limits and usage restrictions below.
  • All usage for all endpoints is tracked, whether free or billable. Each endpoint has a corresponding entitlement attached to it.
Data coverage

Gryd has data from all 50 states and covers more than 2,500 jurisdictions, made up of cities, counties and metropolitan areas. The database holds more than 400M building permits, 100M+ properties and 6.5M+ contractors. Historical coverage spans decades in many jurisdictions, with records dating back over 25 years. Coverage, available fields, and record detail vary by jurisdiction and source. For more on where the data comes from, see Data Sourcing & Methodology.

Coverage also has a narrower meaning in the API. It describes how complete Gryd's permit data is for a permit jurisdiction, and it is measured by comparing Gryd's permit counts with Census survey counts. The free Coverage API exposes the measures behind it, such as population, permits and new construction permits over the last 12 months, the Census ratio, months with new construction data, and active sources in the last 30 days. You decide whether coverage is good enough to make a paid call. Because paid calls are always billed, that decision matters.

A ready-made coverage verdict

The Coverage API is intended to return a ready-made coverage verdict alongside the raw measures, so most customers do not have to build a rule themselves. The interpretation behind the verdict comes from Gryd's analytics team, building on the status definitions in the new permit jurisdictions index. The verdict labels and the rules behind them are still to come from the analytics team. For now the verdict is returned only by the Coverage API, not by Property Search.

If you want more control, you can build your own rule from the measures. The verdict is information only and plays no part in billing.

What customers receive

Each endpoint does one job and returns a specific kind of data. Lookup endpoints and the Coverage API return matches and coverage information at no charge. Paid endpoints return proprietary data and are billed per call. Every paid endpoint is priced separately. For the fields available in Gryd data, see Data Fields & Schema. For other ways to receive data, see Data Products & Delivery.

Free: lookup endpoints and the Coverage API

Endpoint What it returns Billing Pricing
Property Search
GET /property_search
Matches addresses to properties. Returns matched property IDs and basic location data. Free, rate limited No charge
Contractor Search
GET /contractor_search
Matches business names or license numbers to contractors. Returns matched contractor IDs. Free, rate limited No charge
Coverage API (New) Returns coverage measures and a ready-made coverage verdict for a permit jurisdiction. Optional for the customer. Free, rate limited No charge

Paid endpoints: property data

Endpoint What it returns Billing Pricing
Building permits
GET /properties/:id/building_permits
Full permit history for a property: project types, dates, valuations, contractor assignments, and status. Up to 250 (TBC) per page, each call billed separately. Per call Priced separately
System age (New)
GET /properties/:id/system_age
Estimated ages and last-known work dates for roof, HVAC, plumbing, and electrical, synthesized from permit history. Per call Priced separately

Paid endpoints: contractor data

Endpoint What it returns Billing Pricing
Contractor permits
GET /contractors/:id/building_permits
Permit history associated with a contractor: project types, locations, dates, and valuations. Up to 250 (TBC) per page, each call billed separately. Per call Priced separately
Contractor detail
GET /contractors/:id
Business name, classification, location, years in business, and summary statistics. Per call Priced separately
Contractor contacts (New)
GET /contractors/:id/contacts
Verified phone numbers, email addresses, and key personnel. Per call Priced separately
Contractor licenses
GET /contractors/:id/licenses
Verified license numbers, types, status, issuing authority, and expiration dates. Per call Priced separately

Paid endpoints: jurisdiction data

Endpoint What it returns Billing Pricing
Jurisdiction data (New, scope TBD) Jurisdiction-level data drawn from the new permit jurisdictions index: geography and boundaries, demographics, and permit statistics. Specific endpoints to be decided. Per call To be decided
Why the usage model works this way

Under the old model, Gryd decided what counted as covered, and the answer was a single yes or no. In the new model, Gryd gives you the measures and lets you decide. This is better for customers in four ways:

  • The answer fits your use case. Coverage means different things to different customers. A roof-age underwriter needs recent, steady permit data. A new construction analyst needs completeness against the Census. One fixed flag could only serve one of them well. How to Measure Coverage includes examples.
  • You can see why. The old flag was a single value with no explanation. The measures behind the new answer are visible, so you can check an area, explain a decision, and change your rule as your needs change.
  • You can check for free before you spend. The lookup endpoints and the Coverage API cost nothing, so you can screen properties and skip paid calls where Gryd's data is too thin for your purpose.
  • Pricing is simpler. A paid call is billed the same way whether or not the area is covered, so you do not have to work out how Gryd's coverage definition affects your invoice.

Billing is also simpler overall. Every successful call to a paid endpoint is billed, and coverage plays no part. The old billing models split usage into covered and not-covered buckets, with a separate rate available for the latter. That split goes away, and so does any question about whether Gryd's coverage definition should change what a customer pays.

What customers take on

With the ready-made verdict, most customers take on little extra work compared with the old flag: one free call to the Coverage API, and no rule to build. If you want more control, you can build a rule from the measures, and the coverage guide gives you a recipe.

The old billing allowed a separate rate for uncovered zip codes. Any customer on a reduced rate will now pay the standard rate for those calls unless they screen the properties out first.

Rate limits and usage restrictions

Every free API has a rate limit: a cap on how many requests an API client can send in a given period. The lookup endpoints and the Coverage API are all rate limited. Free does not mean unlimited. Specific thresholds are to be confirmed. For the service levels that apply to the API, see API SLA.

An API client that hits a rate limit receives an HTTP 429 response. That is an error response, so it is not a call and is not billed. The client can try again later.

Related documentation