---
title: "API Methods"
canonical: "https://docs.pbs.org/space/localization/5343647/API%20Methods"
format: markdown
---
> Macro (toc)

> ℹ️ **Base Endpoint**
> ℹ️ 
> ℹ️ [http://services.pbs.org/](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 |
| <span style="color: #7a869a">pdp</span> | <span style="color: #7a869a">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. </span> |
| <span style="color: #7a869a">confidence</span> | <span style="color: #7a869a">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".</span> |

### Response example

##### **Find Callsign, Station, and Flagship by Zipcode**

```javascript
{
   "$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 |
| <span style="color: #7a869a">pdp</span> | <span style="color: #7a869a">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. </span> |

### Response example

##### **Find Station by State**

```javascript
{ 
   $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
}
```