Fabric API

This guide assumes that the user has a valid set of credentials to authorize access.

Determining Data Availability

There are two APIs that are provided to determine availability of data. The vintages API indicates which releases of data are available via the API. The layers API indicates the layers that are available such as locations and parcels. The fields API indicates what data attributes are available for a given vintage and layer. Fabric data availability for a given vintage is staggered. The location level data is made available first, with the NetworkPlan and ServiceLandscape information succeeding it at a later date.

curl 'https://api.costquest.com/fabric/vintages' -H 'Authorization: Bearer <token>'

[{
    "vintage": "202406",
    "cqaversion": "9",
    "fccrelease": "06302024",
    "fccversion": "5",
    "ntiaversion": "5_1",
    "vintagename": "june2024"
}, {
    "vintage": "202412",
    "cqaversion": "10",
    "fccrelease": "12012024",
    "fccversion": "6",
    "ntiaversion": null,
    "vintagename": "dec2024"
}]

Identify the layer of data you would like to work with. This is typically the locations layer as it contains useful data elements relating to location, cost, and service availability.

curl 'https://api.costquest.com/fabric/layers' -H 'Authorization: Bearer <token>'

[{
    "layername": "locations"
}, {
    "layername": "parcels"
}, {
    "layername": "footprints"
}]

The fields API is very detailed and its response has been highly limited for display in this guide.

curl 'https://api.costquest.com/fabric/202406/fields/locations' -H 'Authorization: Bearer <token>'

[{
    "format": "f\"{n:d}\"",
    "discrete": 0,
    "fieldname": "location_id",
    "fieldtype": "int",
    "listorder": 1,
    "categories": null,
    "definition": "FCC Unique ID for the fabric location.  Unique ID for the Fabric location. Location_id remains persistent version to version when newer evidence indicates the position of the serviceable location or the presence of a serviceable location on a single location parcel is not significantly changed as compared to the prior version.  A consistent location_id across versions does not mean that the latitude and longitude are unchanged.  A location_id will remain consistent across versions when a different building is selected on a single parcel.  ",
    "reportable": 0,
    "displayname": "Location ID",
    "minimumscope": "Fabric Location",
    "unitofmeasure": "Unique Key",
    "shortdescription": "Unique ID for the Fabric location."
}, {
    "format": null,
    "discrete": 0,
    "fieldname": "address_primary",
    "fieldtype": "text",
    "listorder": 10,
    "categories": null,
    "definition": "Postal address (Street number, street name, directional.  (street type, city, state and ZIP code excluded)",
    "reportable": 0,
    "displayname": "Primary Address Number",
    "minimumscope": "Fabric Location",
    "unitofmeasure": "Indicator (see definition)",
    "shortdescription": "Primary postal address"
}, {
    "format": null,
    "discrete": 1,
    "fieldname": "bdc_fiber",
    "fieldtype": "int",
    "listorder": 25,
    "categories": [{
        "color": "#0a2804",
        "value": "1",
        "category": "Served",
        "maxvalue": null,
        "minvalue": null,
        "listorder": 1,
        "definition": "Served, broadband speed greater than 100 Mbps download x 20 Mbps upload"
    }, {
        "color": "#0ea511",
        "value": "2",
        "category": "Underserved\r\n",
        "maxvalue": null,
        "minvalue": null,
        "listorder": 2,
        "definition": "Underserved, broadband greater than 25 Mbps download x 3 Mbps upload but below Served"
    }, {
        "color": "#14e8d9",
        "value": "3",
        "category": "Unserved",
        "maxvalue": null,
        "minvalue": null,
        "listorder": 3,
        "definition": "Unserved, broadband speed below 25 Mbps download x 3 Mbps upload"
    }],
    "definition": "Highest Fiber speed tier (BDC technology_code in 50) available at Fabric Location expressed as a Broadband Data Collection (BDC) disposition:\n        1 - Served, broadband speed greater than 100 Mbps download x 20 Mbps upload\n        2 - Underserved, broadband greater than 25 Mbps download x 3 Mbps upload but below Served\n        3 - Unserved, broadband speed below 25 Mbps download x 3 Mbps upload\n        [Blank] - No information",
    "reportable": 1,
    "displayname": "BDC Fiber Availability",
    "minimumscope": "Fabric Location",
    "unitofmeasure": "Indicator (see definition)",
    "shortdescription": "Highest Fiber speed tier available at location, expressed as BDC disposition."
}, {
    "format": null,
    "discrete": 0,
    "fieldname": "bdc_fiberproviders",
    "fieldtype": "text",
    "listorder": 26,
    "categories": null,
    "definition": "Distinct concatenated combination of brand_name provider_id and coverage tier [Pipe Delimited].",
    "reportable": 0,
    "displayname": "BDC Fiber Providers",
    "minimumscope": "Fabric Location",
    "unitofmeasure": "Indicator (see definition)",
    "shortdescription": "Distinct id of concatenated Fiber providers."
}]

The response above was filtered to a few customized example response objects for demonstration purposes.

The first object for wiredlfw_dl25_ul3_b_14 identifies a field that contains discrete data (data where the value is itself a category). For discrete values, the categories object will contain an array of all of the potential category values and a textual category field.

Vector Tiles

Vector tiles allow a client to visually render the fabric data layers. These are delivered in Mapbox Vector Tile (MVT) format and they only store a unique UUID per vintage per layer. All other data attributes need to be pulled using the data or bulk APIs by UUID. This is done to secure and protect fabric data attributes from scraping and farming attempts. However, it does introduce additional complexity when building applications. Vector tiles are available via the tiles API.

Availability and Zoom Levels

Tiles are available for three layers of visualization at varying zoom levels.

  1. Locations - Zoom levels 0-14 supported. Full data return only guaranteed at zoom level 13 and larger.
  2. Footprints - Zoom levels 12-14 supported.
  3. Parcels - Zoom levels 12-14 supported.

Accessing and Visualizing Vector Tiles

Tiles are made available using a standard ZXY tiling scheme URL:

https://api.costquest.com/fabric/{vintage}/tiles/{layer}/{z}/{x}/{y}

As an example, for vintage 202406 showing the locations layer, the following URL would be the source:

https://api.costquest.com/fabric/202406/tiles/locations/{z}/{x}/{y}

Keep in mind all requests must be authenticated. Below is an example of the vector tiles being displayed.

The layers can be styled using standard MVT styles. CostQuest provides a standard style file available for all to use:

https://cqazapihttp.blob.core.windows.net/$web/fabricstyles.json

Applications and software that support displaying vector tiles include but are not limited to:

  • Desktop Applications
    • QGIS
    • ESRI ArcGIS Pro
  • Web Mapping SDKs
    • Maplibre GL JS
    • Mapbox GL JS

Working with Fabric Data

Vector tiles are delivered with a single UUID attribute attached. This universally unique identifier (UUID) is unique to a vintage, layer, and feature combination. To retrieve data about features, there are two pathways:

  • The data API will return all accessible fields for a single feature.
  • The bulk API will return up to five fields of information for up to 1,000 features.

Using the data API is straightforward. This is commonly used to return information about map clicks on features. The example below returns the complete view of data for the given UUID in the locations layer:

curl 'https://api.costquest.com/fabric/202406/data/locations?uuid=fa190abf-668d-495d-af4e-75ede107211f' -H "Authorization: Bearer <token>"

The bulk API requires constructing a JSON array of UUIDS as the body of the request. To obtain these UUIDS, an application may identify those that are currently on the screen or loaded, or the collect2 API can be used for custom geographies. Using the collect2 API is documented in more detail in the Collect guide.

Below is an example of calling collect for a boundary then piping the output into a bulk call to retrieve information for four different fields:

curl -X POST 'https://api.costquest.com/fabric/202406/collect' -H 'Authorization: Bearer <token>' -d '{"coordinates":[[[-93.18277691421628,36.72761180221248],[-93.18069178585084,36.72761180221248],[-93.18069178585084,36.72827489013375],[-93.18277691421628,36.72827489013375],[-93.18277691421628,36.72761180221248]]],"type":"Polygon"}' | curl -X POST 'https://api.costquest.com/fabric/202406/bulk/locations?field=address_primary,building_type_code,landuse,bdc_cable' -H 'Authorization: Bearer <token>' -d @-

[
  {
    "uuid": "efbe537a-56fe-4a49-8a55-b636966b84e8",
    "landuse": "1",
    "bdc_cable": 1,
    "address_primary": "3080 STONE RD",
    "building_type_code": "R"
  },
  {
    "uuid": "69c36e1b-8668-492b-9a80-733b3a055be0",
    "landuse": "1",
    "bdc_cable": 1,
    "address_primary": "3076 STONE RD",
    "building_type_code": "R"
  },
  {
    "uuid": "97047428-5bc5-42be-ae56-ce8784ba00aa",
    "landuse": "1",
    "bdc_cable": 1,
    "address_primary": "3084 STONE RD",
    "building_type_code": "R"
  },
  {
    "uuid": "edfd2439-9b5a-4f77-a604-dc8cbf9f9fd6",
    "landuse": "1",
    "bdc_cable": 1,
    "address_primary": "3072 STONE RD",
    "building_type_code": "R"
  },
  {
    "uuid": "66365198-5c9f-43a7-bd8e-f18d0ad9085c",
    "landuse": "1",
    "bdc_cable": 1,
    "address_primary": "3090 STONE RD",
    "building_type_code": "R"
  }
]