Knowledge Base

Knowledge Base

Intro to Gryd by BuildZoom API

Summary

This is an introduction to Gryd by BuildZoom Data's API. Review this document before diving into the more detailed documentation captured in the Property API and Contractor API Guides.

Overview

Each of our APIs is broken down into a Search endpoint and one or more Retrieval endpoints.

Property API

Used to retrieve building permits for specific properties.

Contractor API

Used to retrieve various attributes for specific construction companies.

Sample Requests

Linux & MacOS Example*
curl -XPOST https://api.buildzoomdata.com/v1/properties \
-H 'Requestor-Name: test_user' \
-H 'Api-Key:789_example_123' \
-H 'On-Behalf-Of:test_user_client' \
-H 'Content-Type:application/json' \
-H 'Accept:application/json'
Windows Example*
curl --location --request POST "https://api.buildzoomdata.com/v1/contractors" \
--header "Requestor-Name: test_user" \
--header "Api-Key: 789_example_123" \
--header "On-Behalf-Of: test_user_client" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data-raw "{\"contractor_ids\": [\"WpMM0P\"]}"

Credentials

Include your credentials in the headers of every request. The test credentials included in the examples will give you access to limited data in San Francisco, 94102 for development/testing purposes only. Once you’re a subscribed customer, you will receive credentials with appropriate access.

  • Requestor-Name: This is your user name, provided by Gryd,
  • Api-Key: This is your password, provided by Gryd.
  • On-Behalf-Of: If you’re requesting data on behalf of your customer, you can choose to add that customer’s identifier to this field so we can attribute the request accordingly. If this is applicable to your use case, please read the “Consistent Use of the On-Behalf-Of Header” section below.

Consistent Use of the On-Behalf-Of Header

The property_ids returned from the Properties Endpoint are personalized to the supplied “On-Behalf-Of” header.

This means that any call to the permits end-point for a particular property_id must use the same On-Behalf-Of header that was used to generate that property_id.

If not, the permit response will likely be empty, but it may also return permits for an entirely unrelated property.

Example:

  • If the above request for “1592 Market St” is made with an On-Behalf-Of header of “test_user_client” as shown, the property_id returned is “gp2glK”.
  • If that same request is made with an empty On-Behalf-Of header, the property_id returned is “g4kgOn”.
  • These alternate values will return permits from the permits endpoint only if the matching respective header is supplied during the permit request. This allows traffic from various end_users to be siloed and accounted for separately.

Rate Limiting

Sending too many requests will result in a “429 Too Many Requests” response status code. Rate limits may be adjusted in the future so your code should account for the possibility of a “429” response and act accordingly (e.g. using an exponential backoff).

Requests are currently limited to 2500 every ten minutes across all APIs.

Gryd by BuildZoom Data Snowflake Share