Authentication

Access to the API is authenticated by your API key which will need to be passed in the 1build-api-key HTTP header with each request. API keys are unique to your organization and they come in two types:

• EXTERNAL - for use with backend integrations
• EMBEDDED - for use with client-side integrations

Because the EMBEDDED key must be included in your client-side code it cannot be kept secret. For this reason you must configure referrers in your 1build organization preferences to match the domain name of the website hosting the code which will call the API. For example, if your application is hosted at https://constructionmagic.com/parts/lookup, you would put https://constructionmagic.com/ in your referrers list.

An EXTERNAL key does not require referrers to be configured. Please keep this key private to your organization.

If you need an API key or for help using one please contact help@1build.com.

Your first query

Typically you will use a GraphQL client to help make your queries for you however this is not required. You can make requests directly via HTTP using your language's prefered idioms. If you do want to use a client, there are many options to choose from.

All queries are POST requests to the API endpoint: https://gateway-external.1build.com.

To try out a request, a good place to start is with a sources query. This query will perform a search on the 1build cost database and return matching records.

Request Headers

POST https://gateway-external.1build.com/ HTTP/1.1
content-type: application/json
1build-api-key: 1build_ext.jD0bjzZS.bm7hWEnDb2OffSrTprL385eD9008bLBi

Note the API key is included in the 1build-api-key header and the request is made to the https://gateway-external.1build.com/ endpoint.

Query

query sources($input: SourceSearchInput!) {
    sources(input: $input) {
        nodes {
            id
            name
            calculatedUnitRateUsdCents
            laborRateUsdCents
            materialRateUsdCents
        }
    }

GraphQL lets the client define which fields of a type to return. In this case we request a subset of the full sources schema. Namely the paginated nodes field along with a few fields on each node returned.

Variables

{
    "input": {
        "state": "California",
        "county": "Los Angeles County",
        "searchTerm": "water filtration",
        "page": {
            "limit": 3
        }
    }
}

The sources query takes a SourceSearchInput type as an argument which requires the state, county and searchTerm fields. We are searching for "water filtration" systems in Los Angeles County, California.

The other fields are optional. We could have specified a categoryPath to search only within a certain category hierarchy such as "Plumbing, Rough-In". Categories can be explored using the categoryTreeItems query.

Since sources returns a paginated response we can specify how many results we want returned. We ask for 3 results.

Response

{
    "data": {
        "sources": {
            "nodes": [
                {
                    "id": "8514f9ba-23e6-41c0-914e-a47cb233320c",
                    "name": "1-Stage and Whole House Water Filtration System",
                    "calculatedUnitRateUsdCents": 31502,
                    "laborRateUsdCents": 2856,
                    "materialRateUsdCents": 31025
                },
                {
                    "id": "fd075a43-1c7c-48ef-b804-f6b8da31f2fe",
                    "name": "3-Stage Whole House 20\" Big Water Filtration System",
                    "calculatedUnitRateUsdCents": 52377,
                    "laborRateUsdCents": 2856,
                    "materialRateUsdCents": 51900
                },
                {
                    "id": "1949599e-2adb-475c-8de6-61b987770c78",
                    "name": "4-Stage 300,000 gal. Whole House Water Filtration System",
                    "calculatedUnitRateUsdCents": 48399,
                    "laborRateUsdCents": 2856,
                    "materialRateUsdCents": 47922
                }
            ]
        }
    }
}

The response comes back with the three requested results. These results are sorted by relevancy.

Note: All costs returned by the API are represented as integers in USD cents. To display this value to the end-user you will likely want to convert it into dollars by dividing by 100.

Congratulations! You are now ready to incorporate up-to-date localized cost data into your application.

The most important types to understand when working with the 1build Cost Data API are Source and CategoryTreeItem.

Source

A Source is the basic informational element of our cost data API. It holds cost and procurement information for the product or service in question. Sources can represent many different types of items and are broken down by type into the following broad groups:

SourceType	Description
MATERIAL	A physical piece of construction material, i.e. "5/8" 4X12' Drywall"
EQUIPMENT	A tool or machine, typically for rent, i.e. "15-17' Electric Scissor Lift (Daily Rental)"
ASSEMBLY	A source composed of multiple nested sources of any type, i.e. "Flooring: Sheet Carpet" which includes the nested sources Texture Carpet" and "7/16" 8 lb. Density Carpet Padding"
LABOR	The rate per unit time for a professional to perform a service, i.e. "Tile and Stone Setter"
SCOPE	A scope of work which is billed out to a contractor, typically not hourly, i.e. "Testing - Soil"

Sources come with a lot of additional information which will indicate the name, description, images, price, location, division, etc. For the details of these fields see Source.

Sources are discovered by searching our indexed database for a searchTerm. This is done via the sources query. In addition to a searchTerm you can specify a categoryPath to search only for results in that category path.

CategoryTreeItem

All sources in the API are assigned to a category. This helps to limit the scope when searching for terms which may be common across categories. A category is represented by a CategoryTreeItem which are arranged in a hierarchy.

To discover and browse the category hierarchy make use of the categoryTreeItems query. This query returns a list of nodes and indicates if they have sub-categories below them. By passing a search term into this query you can restrict the results to those categories which have search results within them.

Our recommended approach to designing a user experience around the 1build Cost Data API is composed of a combination of searching and browsing which lets the user quickly narrow down their result set and pick a source which matches their needs.

The idea is to provide search results based on a search term and to allow the user to then optionally narrow down these results by browsing categories.

1. Accept a search term from the user. Either explicitly via a search input box or implicitly based on the name of a pre-existing item.
2. Perform a sources query using the searchTerm field to search all sources for the user's input. This returns the top results for that term.
3. Display the results to the user. Show a detail view for the result if the user clicks on it.
4. Simultaneously with the inital search, perform a categoryTreeItems query using the same searchTerm and an empty categoryPath to get a list of top level categories which contain this term within their child hierarchy.
5. Display the returned categories below the top search results and allow the user to select one.
6. If a category is selected, perform another categoryTreeItems query with the category appended to the categoryPath. This will return sub-categories which contain the search term.
7. Repeat this navigation until the user clicks on a category with no sub-categories.
8. If a category has no sub-categories (indicated by the hasSubCategories field) then it will contain search results. Load these results via a sources query using the full categoryPath and searchTerm.
9. Display these results below the selected leaf category.

As an optional approach, you could implement the above process without an initial search term and let the user just browse categories to find their result. A categoryTreeItems query without a searchTerm will return all categories. The navigation of sub-categories can be implemented as described above. A sources query without a searchTerm will return all results in the given category (up to the requested page limit, 10 by default).

Note: There is no API billing charge for accessing the categoryTreeItems query, only for Source or NestedSource objects returned from the sources query.