Fabric Extensions API

The fabricext API builds on top of the functionality of the fabric API to provide more powerful analysis capabilities and facilitate further understanding of the underlying fabric data.

Match API

The Match API accepts address information and returns a matched location_id. To read more about the Match API, go to the Match API Guide.

History API

While most fabric locations are persistent over time, there exists instability associated with data updates, modeling changes, and challenge data incorporation. The history API provides context to help determine the history of location_ids and their availability across vintages.

curl 'https://api.costquest.com/fabricext/202406/history?location_id=1340212543' -H 'Authorization: Bearer <token>'

[{
    "lastcqaversion": 9,
    "location_id": 1340212543,
    "firstcqaversion": 5,
    "re_location_id": null
}]

For a location_id, a result is returned showing the firstcqaversion and lastcqaversion numbers where the location_id was present. To convert these to other vintage styles, one can use information from the fabric/vintages API.

In addition, if a location was retired (its lastcqaversion is not the current vintage), a process is run that attempts to determine if there is an equivalent location_id in the currently defined vintage of data. These are referred to as retirement equivalencies. An example could be situation in which a location was active, became inactive, and then became active again. Older references to the given location_id can thus often safely be interpreted as the re_location_id -> location_id from the currently requested vintage. These equivalencies exist to provide another layer of stability to the data on top of the existing stability of the location_id.

Locate API

The locate API converts arbitrary geographic coordinates into a location_id and provides context of how accurate the relationship may be.

curl 'https://api.costquest.com/fabricext/202406/locate?latitude=36.6685343&longitude=-80.92023037' -H 'Authorization: Bearer <token>'

[{
    "latitude": 36.6685343,
    "distancem": 0,
    "longitude": -80.92023037,
    "matchtype": "FootprintParcel",
    "sourcekey": null,
    "location_id": 1000006594
}]

The locate API is not just a nearest neighbor search. It utilizes contextual information about parcels, footprints, and locations to make a best-guess determination of a location_id. locate will not always return data as there may not be a suitable relationship between the set of arbitrary coordinates and the fabric data layers to assign a location_id.

If a relationship is established, the matchtype and distancem properties provide context. The distancem captures how far away the location_id is from the provided coordinates, while the matchtype indicates the interaction with the underlying fabric data layers used to determine the match. Valid values for matchtype are documented below.

  • FootprintParcel - The coordinates were a match at a sub-parcel level (both footprint and parcel data layers). This is a very strong match.
  • Footprint - The coordinates were a match at the footprint level. This is a strong match.
  • Parcel - The coordinates were a match at the parcel level. This is an acceptable match in most circumstances, but consideration of the distancem value may be important for certain cases to impose a tolerance.
  • Nearest - The only relationship that could be established was using a nearest neighbor search. This may happen in areas that lack parcel boundaries or areas with extremely large parcels. When considering these matches it’s critical to take into account the distancem value when determining quality.

Reverse Geocoding

The locate API can be used to perform reverse geocoding to fabric locations. This can be achieved using the fabric/data or fabric/bulk APIs to access address data for a given fabric location.

Translate API

The translate API provides methods by which to interpret one identifier in terms of another identifier. A common translation is converting from a location_id to a uuid that the fabric API understands. Keep in mind that while a location_id is persistent across vintages, uuids are unique to each vintage, layer, and feature and cannot be used across vintages or layers.

curl 'https://api.costquest.com/fabricext/202406/translate?src=location_id&dest=uuid&id=1340235422' -H 'Authorization: Bearer <token>'

[{
    "uuid": "affc4405-eb13-41cf-afa4-2b5142b95338",
    "location_id": 1340235422
}]

Summarize API

The summarize API facilitates the summarization of location-based data based on information from the fabric/fields API. To summarize a field, it must be indicated as reportable=1 in the fabric/fields API. Fields are identified as discrete or continuous. Continuous fields may contain categorizations that group their data based on statistical analysis and input from subject matter experts.

curl 'https://api.costquest.com/fabricext/202406/summarize?field=fibergreenfieldpassinv' -H 'Authorization: Bearer <token>' -d '<geojson>'

{
    "data": [{
        "locationcount": 71,
        "fibergreenfieldpassinv": "$500.00 - $1,500.00",
        "fibergreenfieldpassinv_avg": 1207.9764836308482,
        "fibergreenfieldpassinv_cnt": 71,
        "fibergreenfieldpassinv_sum": 85766.33033779022
    }, {
        "locationcount": 29,
        "fibergreenfieldpassinv": "$2,500.00 - $10,000.00",
        "fibergreenfieldpassinv_avg": 3935.019762024754,
        "fibergreenfieldpassinv_cnt": 29,
        "fibergreenfieldpassinv_sum": 114115.57309871787
    }, {
        "locationcount": 36,
        "fibergreenfieldpassinv": "$1,500.00 - $2,500.00",
        "fibergreenfieldpassinv_avg": 1937.3223796821685,
        "fibergreenfieldpassinv_cnt": 36,
        "fibergreenfieldpassinv_sum": 69743.60566855807
    }, {
        "locationcount": 4,
        "fibergreenfieldpassinv": "Greater than $10,000.00",
        "fibergreenfieldpassinv_avg": 16866.568748849233,
        "fibergreenfieldpassinv_cnt": 4,
        "fibergreenfieldpassinv_sum": 67466.27499539693
    }],
    "maxcount": 50000,
    "locationcount": 140
}

By default, categorization is performed on fields with continuous data. To prevent this, pass nocat=1 in the request.

curl 'https://api.costquest.com/fabricext/202406/summarize?field=fibergreenfieldpassinv?nocat=1' -H 'Authorization: Bearer <token>' -d '<geojson>'

{
    "data": [{
        "locationcount": 140,
        "fibergreenfieldpassinv_avg": 2407.7984578604505,
        "fibergreenfieldpassinv_cnt": 140,
        "fibergreenfieldpassinv_sum": 337091.7841004631
    }],
    "maxcount": 50000,
    "locationcount": 140
}

If discrete fields are included, results will be broken out by their distinct values.

curl 'https://api.costquest.com/fabricext/202406/summarize?field=fibergreenfieldpassinv,h3_9,unit_count?nocat=1' -H 'Authorization: Bearer <token>' -d '<geojson>'

{
    "data": [{
        "h3_9": "89265dc00cbffff",
        "locationcount": 1,
        "unit_count_avg": 1.00000000000000000000,
        "unit_count_cnt": 1,
        "unit_count_sum": 1,
        "fibergreenfieldpassinv_avg": 1188.6983940634213,
        "fibergreenfieldpassinv_cnt": 1,
        "fibergreenfieldpassinv_sum": 1188.6983940634213
    }, ...],
    "maxcount": 50000,
    "locationcount": 140
}