Introduction

    API Endpoint

    https://api.fiberhomes.com/v1/address
            

The problem that Fiber Homes aims to solve is that there is currently no way of determining which homes receive fiber internet. The best anyone can hope to find is FCC data which is only accurate to the census block (i.e. an address search there will return the internet offered in the area, not what is offered at the actual address). Fiber Homes is connecting with individual internet service providers to build a dataset that is confirmed at the address level. If an address is in the Fiber Homes database, then it has been confirmed by the provider to be served with fiber-to-the-home*.

By confirming service, Fiber Homes is able to use this API to step in as a go-between and expose fiber-availability data to the general public and new movers, specifically, providing a more-and-more vital answer to a home buyer's question of: but can I get good internet?

* Fiber Homes data also includes other technologies our partners might provide, such as coaxial cable ("coax"), or they have plans to provider fiber to an address in the near future. These responses are labeled as such and are also confirmed.

To use this API, you need an API key. SIGNUP HERE to create a Pro account and then contact support@fiberhomes.com to request your own API key.

get address

                
    # curl with query string 
    curl -X GET "https://api.fiberhomes.com/v1/address? \
        key=your_key& \
        street=120 Nance St& \
        city=Newberry& \
        state=SC& \
        source=demo
                
                
    # curl with content body
    curl -L -m 5 -X GET 'https://api.fiberhomes.com/v1/address' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'key=your_key' \
    --data-urlencode 'street=120 Nance St' \
    --data-urlencode 'city=Newberry' \
    --data-urlencode 'state=SC'
                
            

To get address-specific broadband information you need to make a GET call to the following url:
https://api.fiberhomes.com/v1/address


                
    Fiber Homes confirmed address example :
    
    {
        "global": {
            "assets_cdn_url": "https://assets.newmoverconnect.com",
            "generated_at": "10/25/2022",
            "branding_logo": "https://assets.newmoverconnect.com/web/images/default-logo.png"
        },
        "profile": {
            "firstname": "_EMPTY",
            "lastname": "_EMPTY",
            "agency": "_EMPTY",
            "phone": "_EMPTY",
            "email": "_EMPTY",
            "image": "_EMPTY"
        },
        "address": {
            "street": "120 NANCE ST",
            "city": "NEWBERRY",
            "state": "SC"
        },
        "fh_match": {
            "provider_id": 11,
            "type": "FIBER",
            "type_confirmation_label": "Fiber",
            "name": "WCFIBER",
            "logo": "https://www.dropbox.com/s/nmx6zf8n0vefb90/WCFIBER.png?raw=1",
            "website": "https://www.wcfiber.net/all-services/",
            "telephone": "8443034897",
            "slug": "wcfiber",
            "badge": "https://www.dropbox.com/s/oa3z7egcnamag3r/Badge_WCFIBER.png?raw=1",
            "zillow_badge": "https://www.dropbox.com/s/6hsobxt1g6fpnwk/WCFIBER_ZillowBadge.png?raw=1",
            "needs_construction": false,
            "promo_text": "Get 60 days of free internet service–with no installation fee and no contracts! *Promo available to first-time customers who have purchased their home within the last 60 days. Mention Fiber Homes when placing your order to claim this discount.",
            "promo_title": "New Mover Promo",
            "packages": [
                {
                    "download_speed": "250",
                    "upload_speed": "250",
                    "unit": "Mbps",
                    "price": "$50"
                },
                {
                    "download_speed": "500",
                    "upload_speed": "500",
                    "unit": "Mbps",
                    "price": "$65"
                },
                {
                    "download_speed": "1000",
                    "upload_speed": "1000",
                    "unit": "Mbps",
                    "price": "$80"
                }
            ]
        },
        "fcc": [
            {
                "name": "Xfinity",
                "logo": "https://assets.newmoverconnect.com/logos/Xfinity.png",
                "url": "_EMPTY",
                "phone": "_EMPTY",
                "maxaddown": "200",
                "tech": "Cable",
                "type": "CABLE"
            },
            {
                "name": "Viasat",
                "logo": "https://www.dropbox.com/s/r0io4g5j92atfzn/logo.svg?raw=1",
                "url": "https://www.viasat.com/",
                "phone": "_EMPTY",
                "maxaddown": "35",
                "type": "SATELLITE"
            },
            {
                "name": "HughesNet",
                "logo": "https://assets.newmoverconnect.com/logos/hughes-net.png",
                "url": "_EMPTY",
                "phone": "_EMPTY",
                "maxaddown": "25",
                "type": "SATELLITE"
            }
        ],
        "id": "ae2fbc34-1c40-43f8-869b-5861f6365adb",
        "created_at": "1666711710",
        "context": {
            "description": "confirmed fiber home, pro partner",
            "textA": "This is a certified Fiber Home!",
            "textB": "Powered by WCFIBER.",
            "packages": "https://fiberhomes.com/pro/buying/addr/provider/wcfiber",
            "badge": "https://www.dropbox.com/s/oa3z7egcnamag3r/Badge_WCFIBER.png?raw=1",
            "pro": true,
            "id": 1
        },
        "clean_address": "120 NANCE ST, NEWBERRY, SC",
        "params": {
            "address": "120 Nance St, Newberry, SC",
            "key": "your_key"
        },
        "timestamp": "2022-10-25 15:28:30.839956+00:00"
    }
        
                
            

QUERY PARAMETERS

Field Type Description
key String Your API key.
address String (optional) a full address formatted as "120 Nance St, Newberry, SC"
street String (optional) a street name and number (e.g. "10 Elm St")
city String (optional) a city name (e.g. "Columbus")
state String (optional) a two-letter state abbreviation (e.g. "NC")
source String (optional - default: key.name) short helpful label for request source (e.g. "mysite")

This endpoint will accept either address or all three of street, city, and state. If all four of these parameters are included or only one or two of street, city, and state, you will receive an error response.

The "source" parameter is a secondary means of logging these requests. GET requests are grouped by the API key associated with the request and then can be grouped to a second degree by "source". Including something such as the domain of the site making the request (e.g. "google") as the source, is helpful, but by no means required. The primary use-case is for those using one key across multiple applications.

RESPONSE BODY

The response body has the following relevant top-level information: "address", "fh_match", "fcc", "id", "created_at", "context", "clean_address", "params", and "timestamp".

address : {}

This object contains fiber-homes-standardized versions of the elements of the searched address: street, city, and state. clean_address contains the same information, though joined into a single string.

fh_match : {}

If the searched address is confirmed in Fiber Homes database, its corresponding information will populate here. Fiber Homes providers may have any of the following useful elements associated with their account:

  • type: "FIBER" or "CABLE"
  • name: the provider's consumer-friendly name
  • logo: a .png of the provider's logo
  • website: the url provided to Fiber Homes by the provider; this could link to the provider's home page or their packages and pricing page (at the discretion of the provider)
  • telephone: a 10-digit phone number, most often corresponding with the provider's sales department
  • badge: a .png of the provider's Fiber Homes Badge
  • zillow_badge: a .png of a modified version of the provider's Fiber Homes Badge
  • needs_construction: a boolean value designating whether the address searched would require additional construction for fiber-to-the-home to be made possible.
  • promo_text: any promotion the provider may be offering through fiberhomes.com
  • packages: a list of package objects, where each package lists download_speed, upload_speed, unit (as either Mbps or Gbps/Gig), and price; this list is not exhaustive, but reflects as many as three of the packages included in the Fiber Homes database

fcc : []

The Fiber Homes Address API will also query FCC 477 data, which, though less reliable, helps round out data offerings. As a reminder, FCC data should always be presented with a qualifier: "results are accurate to the census block as of the previous update of FCC 477 data (which, at the time of writing this, was) December 2020." The data here is sorted highest to lowest by down speed (i.e. fastest internet to slowest) and includes the following details:

  • name: the provider's consumer-friendly name
  • logo: a image file of the provider's logo
  • url: either the home page of the provider's website or an affiliate link used by Fiber Homes, at the discretion of Fiber Homes
  • phone: a 10-digit phone number, most often corresponding with the provider's sales department
  • maxaddown: max advertised download speed; this field corresponds with the fh_match field, download_speed
  • type: the technology offered at the address (e.g. "FIBER", "CABLE", "SATELLITE", "WIRELESS", "DSL" etc.)

context : {}

This object contains high-level fields for creating simple widgets without the need to wrap this reponse in new logic. Ideally, an application can use the information from context to generate a "best single match" type of result. This object contains the following details:

  • description: a high-level description of the type of response
  • textA: text corresponding with the response type; this text might possibly only be coherent alongside textB
  • textB: ext corresponding with the response type; this text might possibly only be coherent alongside textA
  • packages: a url to a more robust view of the provider's packages and pricing on fiberhomes.com ( example)
  • badge: a .png of the provider's Fiber Homes Badge
  • id: an id corresponding with the type of result; context ids can be any of the following:
    • 1 confirmed fiber home: match in Fiber Homes data, is fiber
    • 2 confirmed non-fiber: match in Fiber Homes data, is cable/coax
    • 3 confirmed non-fiber, coming soon: match in Fiber Homes data, currently not served by the provider, but fiber is fewer than 6 months out
    • 4 confirmed non-fiber, coming soon, currently lit: match in Fiber Homes data, currently not served by the provider, but fiber is fewer than 6 months out, and the provider currently serves the address with cable/coax
    • 5 FCC data, unconfirmed fiber: provider serves fiber nearby
    • 6 FCC data, unconfirmed non-fiber: provider serves a non-fiber technology nearby

params : {}

The raw parameters submitted in the request.

put address

                
    # curl with query string 
    curl -X GET "https://api.fiberhomes.com/v1/address? \
        key=your_api_key& \
        street=123 Example St& \
        city=Columbia& \
        state=SC& \
        provider=3"
                
                
    # curl with content body
    curl -L -X PUT 'https://api.fiberhomes.com/v1/address' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'key=your_api_key' \
    --data-urlencode 'street=123 Example St' \
    --data-urlencode 'city=Columbia' \
    --data-urlencode 'state=SC' \
    --data-urlencode 'zipcode=29212' \
    --data-urlencode 'provider=3' \
    --data-urlencode 'fiber=true' \
    --data-urlencode 'coming_soon=false' \
    --data-urlencode 'currently_lit=true'
                
            

In order to best perserve resources, there is a unique constraint on the columns of street, city, state, and provider id in the Fiber Homes address table i.e. there are no duplicate addresses on the provider level. If one were to attempt to write an address with a foreign key to "Provider A", but "Provider A" already had the address, the constraint would produce a conflict and we would attempt to update the other fields of the address instead of writing the address a second time. tl;dr every Insert is actually an Upsert, so POSTs are not supported, only PUTs.

                
    PUT response example:

    {
        "address": [
            {
                "street": "123 EXAMPLE ST",
                "city": "COLUMBIA",
                "state": "SC",
                "zipcode": "29212",
                "provider_id": 3,
                "id": 2496663,
                "latitude": "None",
                "longitude": "None",
                "fiber": true,
                "coming_soon": false,
                "currently_lit": true,
                "source": "cdg"
            }
        ],
        "timestamp": "2022-07-08 19:29:57.067451+00:00"
    }
                
            

To add a fiber-to-the-home address from one of our ISP partners you need to make a PUT call to the following url:
https://api.fiberhomes.com/v1/address


QUERY PARAMETERS

Field Type Description
key String Your API key.
street String a street name and number (e.g. "10 Elm St")
city String a city name (e.g. "Columbus")
state String a two-letter state abbreviation (e.g. "NC")
zipcode String (optional - default: None) 5-digit zip code (e.g. "36036")
provider Integer Provider ID supplied by Fiber Homes (e.g. 3)
fiber Boolean (optional - default: True) This address receives fiber-to-the-home (e.g. True)
coming_soon Boolean (optional - default: False) This address does not have fiber-to-the-home presently, but will within 6 months (e.g. False)
currently_lit Boolean (optional - default: True) The address is being served some technology by the corresponding provider (e.g. True)

RESPONSE BODY

The response for a successful PUT request is the row from the database and a timestamp for the entry. Any new information present is present because of default values being filled in such as id, fiber, coming_soon etc.

throttling

Currently we do not throttle API requests unless those requests are determined to be abusive or malicious. We reserve the right to change these throttling limits with notice, and we will update this documentation to announce any such change.

If you are throttled for any reason, you will receive a status code 429 response.

Keep in mind that you're using a shared platform, and you should still be deliberate in how you design your application to use our API. Applications that are determined to be abusive or malicious, or that otherwise monopolize the use of our API may be throttled.

If we detect that your application is nearing the point where we may have to throttle it, we will likely pro-actively reach out to you to discuss how you can optimize your usage. If you have any questions, feel free to contact us at support@fiberhomes.com and we'd be glad to help!

Status Codes

The Fiber Homes API uses standard HTTP status codes:

Status Code Description
200 Successful request. Congratulations.
400 Missing query parameters; review the Query Parameters section of this documentation.
401 Unauthorized to make this request. Either you are trying to make an Unauthorized method or your key is invalid.
404 The endpoint you're looking for was not found. Refer to the endpoints available in this documentation.
429 You're being throttled. Chill.
500 Internal server error; email support@fiberhomes.com to give us a head's up.

Known Limitations

Currently, the search function handles traditional addresses consistently well. Often times, when an address request is returning a response that doesn't look correct, the reason is because it is recorded with a typo or in an otherwise strange way on the database side. The data is standardized with a few heuristics, but there are always edge cases that slip through--the problem of matching addresses is an involved one.

One of the primary areas where addresses are not matched as they should is with respect to multi-dwelling units ("MDUs"). Because there are so many possible ways to designate an individual unit, the Fiber Homes search looks instead just for the street number, name, and postal code suffix (directional prefix and suffix if present). For example, if you want to GET 1 Main St #3 (or APT A, Suite 2A etc.), Columbus, Ohio, your search should just include "1 Main St" as the street parameter, or only 1 Main St, Columbus, Ohio as the address parameter.

Similarly, listings recorded with the format of "Lot #1, Madison, WI" will not be found in Fiber Homes data and may not return a result from the FCC.

New addresses are always being built out with fiber. Though our data is being updated at a regular cadence, there will be windows of time where a home receives fiber-to-the-home but is not designated as such based on a call. Update frequency is only getting more and more regular, so this should be less and less of a limitation over time.

Lastly, because the API relies on FCC data as the fallback for returning helpful information, it also inherits the lackings of the FCC data. Such data, as mentioned earlier in this documentation, is accurate only to the census block and only updated every 6 months at best (as of July 2022, the FCC data is 2 years). Take FCC data responses with a grain of salt. We are always looking for better fallback data.