Linking results from the FCC's TV Query API to the FCC's TV Stations Profiles API

Question

The FCC has at least two APIs related to broadcast station data. One is TV Query, which can return pipe-delimited results like this (keys):

|K02JU       |-         |TX |2   |DA  |                    |-  |-  |LIC    |SELAWIK                  |AK |US |BLTTV  -19800620IA  |0.018  kW |-         |0.0     |-       |11543      |N |66 |35 |57.00 |W |160 |0  |0.00  |CITY OF SELAWIK                                                             |   0.00 km |   0.00 mi |  0.00 deg |72.    m|H       |20773     |210.    |-       |0.      |21309     |-  |
|K02KB       |-         |TX |2   |DA  |                    |-  |-  |LIC    |ALLAKAKET                |AK |US |BLTTV  -19800908IY  |0.018  kW |-         |0.0     |-       |1036       |N |66 |33 |53.00 |W |152 |38 |38.00 |ALLAKAKET CITY COUNCIL                                                      |   0.00 km |   0.00 mi |  0.00 deg |113.   m|H       |20773     |90.     |-       |0.      |23306     |-  |

I'm trying to use the facilityID field from its results as input for the FCC's TV Stations API (specifically, the broadcast contour method [see example]). The problem is that many of the facilityIDs yield no results. I'm guessing this simply means that the TV Query query is scooping up types of facilities that aren't in the same category as those in the Stations database.

So: How can I refine the TV Query query to only include the "right type" of station?

Answer 1

This is the sort of issue that can arise when trying to combine data from multiple sources, in this case two apparently distinct APIs.

The Developer page gives some brief instructions as you point out, but importantly there seems to be no method for retrieving a list of all valid Facility IDs. This is an oversight in my opinion, as a "Facility Details" request, for example, requires a Facility ID as a parameter. It appears the only way to get valid Facility IDs, other than your method, is to use the "Facility Search" API method, which allows you to search for stations using "call sign, frequency, city, state, channel, or Nielsen DMA", and returns a Facility ID among other data.

You haven't stated whether you're working manually or programmatically, but as a programmer if I were doing this and needed to get a list of Facility IDs, I would probably use the Facility Search to return data for each of the 50 states, then combine these. This would be relatively straightforward in code - loop through the state codes for each of the 50 states, as per the example given for New York:

http://data.fcc.gov/mediabureau/v01/tv/facility/search/NY.json

For each state, scrape off the Facility IDs, which ought to result in a complete list of valid Facility IDs for the USA. This assumes that there are no facilities that are somehow independent of states, or have no state recorded.

Having said all that, I would probably take a minute to send a quick email to developer@fcc.gov, asking whether it is possible to retrieve a list of all Facility IDs via some unpublished API method. The amount of support you can expect for using an essentially free and thus unsupported service may vary of course.

Answer 2

First I'd note that most of this data is available for bulk download as part of the CDBS--see more here. Building your own clone of the data takes some time, but is worth it if you plan to do much work with this data.

I think you're correct that not all TV stations returned in the query have profiles. I'm not sure of the criteria for inclusion, but would guess that it's based on "service" on the query page you link. I suspect that low power TV stations, TV translators/repeaters, auxiliary stations and more aren't included.

No matter which way you go, you'll know the most if you run your own copy of CDBS. If you can't do that, you might try downloading just one service type at a time and querying the station lookup to see if that type is included. Also, you probably want to call up FCC and ask. Dale Bickel -- dale.bickel@fcc.gov -- knows about the contours, though I don't think the API stuff is in his bailiwick.

That said, I believe that there are contours available for all of these on the contour page. They aren't in such a convenient format (my recollection is they are polygons with 360 vertices) but they are in a simple format that you should be able to convert to something else. (A few years ago I wrote a python converter that will dump them either to postgis or shapefile, I forget which, so get in touch with me directly if you need this).