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 developer account. You should be contacted by support@fiberhomes.com within 1 to 2 business days about your 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://assets.fiberhomes.com/logos/WCFIBER.png",
"website": "https://www.wcfiber.net/all-services/",
"telephone": "8443034897",
"slug": "wcfiber",
"badge": "https://assets.fiberhomes.com/badges/WCFIBER.png",
"zillow_badge": "https://assets.fiberhomes.com/badges/zillow/WCFIBER.png",
"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"
}
],
"all_matches": [
{
"provider_id": 11,
"type": "FIBER",
"type_confirmation_label": "Fiber",
"name": "WCFIBER",
"logo": "https://assets.fiberhomes.com/logos/WCFIBER.png",
"website": "https://www.wcfiber.net/all-services/",
"telephone": "8443034897",
"slug": "wcfiber",
"badge": "https://assets.fiberhomes.com/badges/WCFIBER.png",
"zillow_badge": "https://assets.fiberhomes.com/badges/zillow/WCFIBER.png",
"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"
}
]
}
]
"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://assets.fiberhomes.com/badges/WCFIBER.png",
"pro": true,
"id": 1
},
"confirmed": true,
"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") |
| direct | Boolean | (optional - default: False) redirects to the corresponding full report on newmoverconnct.com |
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.
As of December 2022, you can now add the "direct" parameter with a value of "True" to go directly to the full broadband property report
corresponding with the searched address on newmoverconnect.com (see example).
The API response is categorically different with this added parameter. Instead of returning as one field in a complete response body an id,
the response header "Location" is set to https://newmoverconnect.com/result?id=unique-id. Such a response
will redirect your browser to the url value here.
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". Critically, the boolean field "confirmed" was also added, which returns "True" in the event of an address match, and "False" in the event of relying entirely on FCC data.
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 namelogo: a .png of the provider's logowebsite: 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 departmentbadge: a .png of the provider's Fiber Homes Badgezillow_badge: a .png of a modified version of the provider's Fiber Homes Badgepromo_text: any promotion the provider may be offering through fiberhomes.compackages: a list of package objects, where each package listsdownload_speed,upload_speed,unit(as either Mbps or Gbps/Gig), andprice; 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 namelogo: a image file of the provider's logourl: either the home page of the provider's website or an affiliate link used by Fiber Homes, at the discretion of Fiber Homesphone: a 10-digit phone number, most often corresponding with the provider's sales departmentmaxaddown: max advertised download speed; this field corresponds with thefh_matchfield,download_speedtype: the technology offered at the address (e.g. "FIBER", "CABLE", "SATELLITE", "WIRELESS", "DSL" etc.)
all_matches : []
As of June 2023, you will see a semi-redundant field, "all_matches", in the response body where the Fiber Homes match(es) are returned as a list of objects. As we've grown, we've begun to see "overbuilds" or addresses where multiple providers have built fiber connections to the same residence. To most accurately reflect this, the "all_matches" field will return all exact matches to the queried address, while "fh_match" returns the "top match" at the address.
context : {}
This object contains high-level fields for creating simple widgets without the need to wrap this response 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 responsetextA: text corresponding with the response type; this text might possibly only be coherent alongsidetextBtextB: ext corresponding with the response type; this text might possibly only be coherent alongsidetextApackages: 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 Badgeid: 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'll 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 2023, the FCC data is 2 years old). Take FCC data responses with a grain of salt. We are always looking for better fallback data.