Knowledge Base
Knowledge Base
Glossary
This glossary defines the terms used across Gryd's documentation. For definitions of individual data fields, see the Data Dictionary.
Permits and properties
| Term | Definition |
|---|---|
| Building permit | An official document issued by a local government authority, typically a city or county building department, that gives legal permission to begin a specific construction project. Permits exist for public safety. They allow the local building department to review a project's plans before construction starts and to inspect the work as it happens, to confirm it meets building codes and structural standards, electrical and plumbing codes, and zoning requirements. |
| Building Permits Plus | A data dictionary that includes all fields in the standard Building Permits data dictionary, along with additional contractor contact information. |
| City jurisdiction | An incorporated municipality with its own permitting office. Each city is treated as a separate source. |
| County jurisdiction | A county permitting source, which generally covers only the unincorporated areas of a county. Coverage for a county source does not automatically include incorporated cities within that county. For example, Pasco County, Florida, covers unincorporated Pasco County but not New Port Richey, which has its own permitting office. |
| Job value | The estimated total project cost, including labor and materials. The contractor typically provides this value when applying for the permit, and it may be understated by 25-50%. Treat it as directional rather than precise. |
| Jurisdiction | The geographic territory or government body, such as a city, town, county, or township, that has the legal authority to govern, regulate, and enforce laws within its borders. In construction, the jurisdiction is the local agency responsible for reviewing building plans and issuing permits for projects within its boundaries. |
| Permit classifier | A Gryd classification that identifies each permit as residential or commercial and assigns one or more of 35+ project-type tags, such as roofing, electrical, kitchen remodeling, or additions. Each classifier evaluates multiple text fields and permit attributes. |
| 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. |
| Permit status | Where a permit is in its lifecycle. A permit typically moves through four stages, and it can be cancelled at any stage. Gryd standardizes 15 permit statuses into four categories. Status text is provided by each jurisdiction and varies in wording, capitalization, and completeness. Applied: the permit is submitted (usually by the contractor) and pre-inspections or reviews are conducted. Standardized from applied, triage, filed, and plancheck. Issued: once approved, the permit is issued and work can begin. Standardized from approved, issued, and reinstated. Completed: after work is finished or a successful final inspection occurs, the permit is marked complete. Standardized from complete and final. Cancelled: a permit can be cancelled at any stage for various reasons. Standardized from rejected, revoked, canceled, withdrawn, expired, and suspended. |
| Raw type and subtype | The type and subtype fields that come directly from each permitting jurisdiction. They are not standardized at the source, so Gryd retains them and uses them alongside free-text work descriptions when applying permit classifiers. |
Contractors
| Term | Definition |
|---|---|
| Active license | Gryd determines active status primarily from issue and expiration dates rather than the raw status label. A license is counted as active when it expires in the future, with a small allowance for renewal processing, or when it has no expiration date but was issued within the previous two years. A record may display an active-looking status after expiration, but it will not be included in Gryd's active-license counts. |
| Contractor ID | An identifier intended to represent one construction business or individual operating under one name within one state. Gryd creates these profiles by connecting business names, headquarters addresses, contact details, license numbers, and employee names across license and permit records. Because matching is performed at the state level, the same business operating in multiple states will typically have a separate contractor ID in each state. |
| Contractor type | A Gryd classification based on several signals, including the most common license types on the profile, the mix of permit project types, and the contractor's business name. Each contractor is assigned one primary type. |
| Licensee fields | The raw, unaltered values provided by the issuing jurisdiction. They are authoritative for that specific license record. The contractor-level profile reflects Gryd's matching and standardization logic, which links licenses using business name, address, contact details, and other signals. |
| Registration record | A record that comes from a registration-only source rather than a formal licensing board. A blank license number is expected for these records. A registration is considered active when it falls within the previous two years. |
Coverage
| Term | Definition |
|---|---|
| Coverage | Whether Gryd holds good permit data for an area. It is measured per permit jurisdiction by comparing Gryd's permit counts with Census survey counts. See How to Measure Coverage. |
| 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. Customers can use it as is, or build their own rule from the measures. |
| 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. |
API usage and billing
For how these terms fit together, see the Gryd API Usage Model.
| Term | Definition |
|---|---|
| API client | The software a customer uses to send API requests to Gryd's endpoints. The customer owns it and runs it in the customer's own infrastructure, not Gryd's. The customer is the business that pays. The API client is the system acting on its behalf. |
| 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 Gryd sends 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 that Gryd completes successfully. An error response, such as a server error (HTTP 500) or a client error (HTTP 4xx), does not count as a call and is never billed. Calls are the unit Gryd bills on, but not every call is billable. Calls to paid endpoints are billed. Calls to lookup endpoints and to the Coverage API are free. |
| Endpoint | A single API address an API client calls to ask Gryd for something, such as GET /property_search. Each endpoint does one job. Endpoints are grouped into types, such as lookup endpoints and paid endpoints. |
| Lookup endpoint | A type of endpoint that matches a customer's data, such as addresses or contractor names, to the records Gryd holds. This is what Gryd means by matching, and it is always free. There are two: Property Search and Contractor Search. They return matched IDs only, with no proprietary data. |
| 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. |
| Paid endpoint | A type of endpoint that returns proprietary data. Always billed per call, whether or not the area is covered. |
| Permit page | Permit endpoints return up to 250 (TBC) permits per page. Each page is a separate call, billed separately. |
| Proprietary data | What Gryd charges for: permits, licenses, contacts, system age, and jurisdiction data. |
| 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 is an error response, so it is not a call and is not billed. |
Data products and delivery
| Term | Definition |
|---|---|
| API Access | On-demand, real-time access to property permit history and contractor data via REST API. It supports batch requests, returns results with sub-second latency, and uses header-based credential authentication. |
| Bulk Datasets | Full historical dataset exports, delivered as file exports on a weekly or monthly cadence. Customers can receive full snapshots or incremental updates. Files are available as gunzipped CSV (.csv.gz). See Bulk Data Delivery via AWS S3. |
| Custom Data Solutions | Tailored data deliveries for organizations with specific business requirements. |
| Full delivery | A delivery used to periodically resynchronize your data, including changes not represented in incremental files, such as deletions and some updates to Gryd-generated metadata. |
| Gryd Explorer | A web-based UI for browsing contractors and recent projects, creating custom reports, and exporting contact lists. |
| Incremental delivery | A delivery that helps you keep permit data current without reprocessing the much larger full delivery each time. Incremental files use the same schemas as full files and contain records added or updated since your previous incremental delivery. They do not replace full files. See Incremental Data Delivery via AWS S3. |
| Primary key | The field that identifies each record in a delivered file: building_permit_id for building_permits, property_id for properties, and contractor_id for contractors. |
| Upsert | An operation that inserts a record when its primary key is new and updates the existing record when that key is already present. |
How Gryd builds its data
For more on where the data comes from, see Data Sourcing & Methodology.
| Term | Definition |
|---|---|
| Construction knowledge graph | The structure Gryd maps data into, enabling cross-entity relationship building, such as linking a permit to the licensed contractor who pulled it. |
| Data pipeline | The five-stage process Gryd follows to transform raw public records into a clean, enriched, analytics-ready dataset: identification, extraction, transformation, mapping, and enrichment. |
| Enrichment | Pipeline stage 5. A bundle of ML models develops second-order data points such as entity type classifications and project categories. Data is then aggregated for usage. |
| Extraction | Pipeline stage 2. A variety of methodologies are applied to extract data from each source, accounting for variation in format, cadence, and access method across thousands of jurisdictions. |
| Identification | Pipeline stage 1. A research team maintains and prioritizes a living index of public data sources: state and license boards, building and planning departments, and county clerk offices. |
| Mapping | Pipeline stage 4. Data is mapped into a construction knowledge graph, enabling cross-entity relationship building. |
| Transformation | Pipeline stage 3. Extracted data is stored in a nested JSON format in Postgres, then structured and schematized through a combination of human interpretation and machine-learning methods. |