API Methods

Base Endpoint

http://services.pbs.org/

Search Parameters

Parameter Name	Guidelines	Examples
`zip`	ZIP code must have 5 characters.	22202, 05354
`stateabbr`	State must have a universally accepted two letter abbreviation.	AL, VA
`ip`	Must be complete and valid IP address.	138.88.141.44

Search Callsign Availabilities by ZIP Code

Endpoint

http://services.pbs.org/callsigns/zip/<zip>.json

Returns a list of ranked flagship stations, and select metadata, for a given zip code.

Parameter

Parameter	Description
zip	A valid 5 digit zip code. Examples: 22202, 99508

Noteworthy Fields in Response

Fields	Description
callsign	The four-character, FCC-assigned, flagship station entity. Examples: WETA, KAKM
rank	Ascending order of available stations, based on reach within a given ZIP code. The station with the largest reach is ranked "1".
common_name	The station's "display" name, used across PBS platforms. Example: Panhandle PBS
short_common_name	The station's "diaplay" name used on PBS platforms where space may be limited. Example: PPBS
mailing_city	City in which the station is located
mailing_state	State in which the station is located
website	Station site URL
membership_url	Station general "donate" URL
pdp	Denotes "Program Differentiation Plan" stations, where the value is true/false. This legacy field remains in the response, but is no longer used. In the past, it was used to help calculate station rank order.
confidence	This legacy field remains in the response, but is no longer used. In the past, it was used to help calculate station rank order. All stations now have a confidence value of "100".

Response example

Find Callsign, Station, and Flagship by Zipcode

{
   "$type":"application/vnd.pbs-collection+json",
   "$self":"http://services.pbs.org/callsigns/zip/22202.json",
   "$items":[
      {
         "confidence":100,
         "$type":"application/vnd.pbs-resource+json",
         "$class":"CallSign2ZipMapping",
         "rank":1,
         "$self":"http://services.pbs.org/callsigns/zip/22202/WETA.json",
         "$links":[
            {
               "callsign":"WETA",
               "$links":[
                  {
                     "$type":"application/vnd.pbs-resource+json",
                     "mailing_state":"VA",
                     "short_common_name":"WETA",
                     "$class":"Station",
                     "$relationship":"parent",
                     "$self":"http://services.pbs.org/station/139.json",
                     "mailing_city":"Arlington",
                     "$created":"2012-11-12T04:54:55-05:00",
                     "$links":[
                        {
                           "$type":"application/vnd.pbs-collection+json",
                           "$relationship":"children",
                           "$self":"http://services.pbs.org/callsigns/station/139.json",
                           "$elements":"Callsign",
                           "$accepts":[
                              {
                                 "$type":"application/vnd.pbs-resource+json",
                                 "$class":"Callsign"
                              }
                           ]
                        },
                        {
                           "$relationship":"flagship",
                           "$type":"application/vnd.pbs-resource+json",
                           "$class":"Callsign",
                           "callsign":"WETA",
                           "$self":"http://services.pbs.org/callsign/WETA.json"
                        }
                     ],
                     "common_name":"WETA Television and Radio",
                     "$edited":"2012-11-12T04:54:55-05:00"
                  },
                  {
                     "$type":"application/vnd.pbs-collection+json",
                     "$relationship":"children",
                     "$elements":"Feed",
                     "$self":"http://services.pbs.org/feeds/callsign/WETA.json"
                  }
               ],
               "$type":"application/vnd.pbs-resource+json",
               "$class":"Callsign",
               "$relationship":"related",
               "$self":"http://services.pbs.org/callsign/WETA.json"
            }
         ]
      },
      ... more elements here ...
   ],
   "$elements":"CallSign2ZipMapping",
   "$accepts":[
      {
         "$type":"application/vnd.pbs-resource+json",
         "$class":"CallSign2ZipMapping"
      }
   ]
}

Search Station by State

Endpoint

http://services.pbs.org/stations/state/<stateabbr>.json

Returns a list of available flagship stations, and select metadata, for a given state abbreviation. This includes available stations which are outside the given state.

Ordering Rules

First, by internal rank assignment, if present. (The rank order is not exposed in the API. Most stations have the same rank number so the following rules will apply.)
Then, stations from the state entered in the URL, sorted alphabetically by common_name_short.
Next, by available stations that are outside the state entered in the URL, sorted alphabetically by common_name_short.
Last, available stations where the "pdp" value is "true".

Parameter

Parameter	Description
stateabbr	A valid state abbreviation. For example: AL, VA

Noteworthy Fields in the Response

Fields	Description
callsign	The four-character, FCC-assigned, flagship station entity. Examples: KACV
common_name	The station's "display" name, used across PBS platforms. Example: Panhandle PBS
short_common_name	The station's "diaplay" name used on PBS platforms where space may be limited. Example: PPBS
mailing_city	City in which the station is located
mailing_state	State in which the station is located
website	Station site URL
membership_url	Station general "donate" URL
pdp	Denotes "Program Differentiation Plan" stations, where the value is true/false. This legacy field remains in the response, but is no longer used. In the past, it was used to help calculate station rank order.

Response example

Find Station by State

{ 
   $type: "application/vnd.pbs-collection+json",
   $items: [ 
     { 
	$type: "application/vnd.pbs-resource+json",
   	$class: "Station2StateMapping",
	$links: [ 
           { 
		$type: "application/vnd.pbs-resource+json",
		mailing_state: "AK",
		short_common_name: "KAKM",
		$class: "Station",
		$relationship: "related",
		$self: http://services.pbs.org/station/26.json,
		mailing_city: "Anchorage",
		$created: "2012-11-12T04:54:52-05:00",
		$links: [ 
		   { 
			$type: "application/vnd.pbs-collection+json",
			$relationship: "children",
			$self: http://services.pbs.org/callsigns/station/26.json,
			$elements: "Callsign",
			$accepts: [ 
			   { 
				$type: "application/vnd.pbs-resource+json",
				$class: "Callsign"
			   }
			]
		   },
		   { 
			$relationship: "flagship",
			$type: "application/vnd.pbs-resource+json",
			$class: "Callsign",
			callsign: "KAKM",
			$self: http://services.pbs.org/callsign/KAKM.json
		   }
		],
		common_name: "KAKM-TV Channel 7",
		$edited: "2012-11-12T04:54:52-05:00"
	   }
	],
   $self: http://services.pbs.org/stations/state/AK/26.json
},
{ 
   $type: "application/vnd.pbs-resource+json",
   $class: "Station2StateMapping",
   $links: [ 
	{ 
	   $type: "application/vnd.pbs-resource+json",
	   mailing_state: "AK",
	   short_common_name: "KTOO",
	   $class: "Station",
	   $relationship: "related",
	   $self: http://services.pbs.org/station/106.json,
	   mailing_city: "Juneau",
	   $created: "2012-11-12T04:54:54-05:00",
	   $links: [ 
		{ 
		   $type: "application/vnd.pbs-collection+json",
		   $relationship: "children",
		   $self: http://services.pbs.org/callsigns/station/106.json,
		   $elements: "Callsign",
		   $accepts: [ 
			{ 
			   $type: "application/vnd.pbs-resource+json",
			   $class: "Callsign"
			}
		   ]
		},
		{ 
		   $relationship: "flagship",
		   $type: "application/vnd.pbs-resource+json",
		   $class: "Callsign",
		   callsign: "KTOO",
		   $self: http://services.pbs.org/callsign/KTOO.json
		}
	   ],
	   common_name: "KTOO",
	   $edited: "2012-11-12T04:54:54-05:00"
	}
   ],
   $self: http://services.pbs.org/stations/state/AK/106.json
},
{ 
   $type: "application/vnd.pbs-resource+json",
   $class: "Station2StateMapping",
   $links: [ 
	{ 
	   $type: "application/vnd.pbs-resource+json",
	   mailing_state: "AK",
	   short_common_name: "KUAC",
	   $class: "Station",
	   $relationship: "related",
	   $self: http://services.pbs.org/station/68.json,
	   mailing_city: "Fairbanks",
	   $created: "2012-11-12T04:54:53-05:00",
	   $links: [ 
		{ 
		   $type: "application/vnd.pbs-collection+json",
		   $relationship: "children",
		   $self: http://services.pbs.org/callsigns/station/68.json,
		   $elements: "Callsign",
		   $accepts: [ 
			{ 
			   $type: "application/vnd.pbs-resource+json",
			   $class: "Callsign"
			}
		   ]
		},
		{ 
		   $relationship: "flagship",
		   $type: "application/vnd.pbs-resource+json",
		   $class: "Callsign",
		   callsign: "KUAC",
		   $self: http://services.pbs.org/callsign/KUAC.json
		}
	   ],
	   common_name: "AlaskaOne",
	   $edited: "2012-11-12T04:54:53-05:00"
	}
   ],
   $self: http://services.pbs.org/stations/state/AK/68.json
  }
],

$elements: "Station2StateMapping",

$self: "http://services.pbs.org/stations/state/AK.json"


}

Search Zip Code by IP Address

Endpoint

http://services.pbs.org/zipcodes/ip/138.88.141.44.json

Returns the ZIP code, and select geographic metadata, for the provided IP address. No station callsigns are returned.

Parameter

Parameter	Description
ip	A valid IP address. Example: 138.88.141.44

Noteworthy Fields in Response

Fields	Description
zipcode	A valid 5 digit zip code. Examples: 22202, 99508
county_name	Full county name (in all caps) for the corresponding county
county_code	Three-digit code for the corresponding county
state	The two letter abbreviation for a state. Example: VA
state_name	The full name of the state, not abbreviated. Example: Virginia

Response example

Find Zip Code by IP Address

{ 
	$type: "application/vnd.pbs-collection+json",
	$items: [ 
		{ 
			$type: "application/vnd.pbs-resource+json",
			$class: "Zipcode",
			zipcode: "20001",
			$links: [ 
				{ 
					$type: "application/vnd.pbs-collection+json",
					$relationship: "search",
					$self: http://services.pbs.org/callsigns/zip/20001.json,
					$elements: "CallSign2ZipMapping",
					$accepts: [ 
						{ 
							$type: "application/vnd.pbs-resource+json",
							$class: "CallSign2ZipMapping"
						}
					]
				},
				{ 
					$type: "application/vnd.pbs-collection+json",
					$relationship: "related",
					$items: [ 
						{ 
							$links: [ 
								{ 
									state_name: "District of Columbia",
									$type: "application/vnd.pbs-resource+json",
									$class: "State",
									$relationship: "parent",
									$self: http://services.pbs.org/state/DC.json,
									state: "DC",
									$links: [ 
										{ 
											$type: "application/vnd.pbs-collection+json",
											$relationship: "related",
											$elements: "Station2StateMapping",
											$self: http://services.pbs.org/stations/state/DC.json
										}
									]
								}
							],
							$type: "application/vnd.pbs-resource+json",
							county_code: "001",
							$class: "County",
							county_name: "DISTRICT OF COLUMBIA",
							$self: http://services.pbs.org/county/001/state/DC.json
						}
					],
					$elements: "County",
					$self: http://services.pbs.org/counties/zip/20001.json
				},
				{ 
					$type: "application/vnd.pbs-collection+json",
					$relationship: "presence",
					$elements: "Headend",
					$self: http://services.pbs.org/headends/zip/20001.json
				}
			],
			$self: http://services.pbs.org/zipcode/20001.json
		}
	],
	$elements: "Zipcode",
	$self: http://services.pbs.org/zipcodes/ip/138.88.141.44.json
}

Content

Space Tools

Search Parameters

Search Callsign Availabilities by ZIP Code

Parameter

Noteworthy Fields in Response

Response example

Search Station by State

Ordering Rules

Parameter

Noteworthy Fields in the Response

Response example

Search Zip Code by IP Address

Parameter

Noteworthy Fields in Response

Response example

Content

Space Tools

Breadcrumbs

API Methods

Search Parameters

Search Callsign Availabilities by ZIP Code

Parameter

Noteworthy Fields in Response

Response example

Search Station by State

Ordering Rules

Parameter

Noteworthy Fields in the Response

Response example

Search Zip Code by IP Address

Parameter

Noteworthy Fields in Response

Response example