Overview

This document is intended for developers who want to write applications that interact with Station Manager. It explains basic concepts of Station Manager and the API and provides an overview of the different functions supported by the API. The public call returns all publicly-accessible data and can be filtered by station flagship callsign.

Getting started

Before using the API, familiarize yourself with the following:

  • Core concepts of the JSON (JavaScript Object Notation) data format. JSON is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.


Resources and resource types

A resource is an individual data entity with a unique identifier. The table below describes the different types of resources and the different calls you can make when using this API.


Resource typeDescription
Station </resources/station>Station object

Supported actions


ActionDescription
getRetrieves (GET) a specific resource.

The table below identifies the (subset of) operations that are supported for different types of resources. Each resource may support some particular actions which are described on their individual specification page.


Resource typeget
Station yes

HTTP request headers

The required headers used by the API are listed below. At the moment we’re only accepting JSON and JSONAPI-specific header.


HeaderMeaningValues
Content-TypeThe content type of the payloadapplication/json
Content-TypeThe content type of the payloadapplication/vnd.api+json

Possible fields returned


Parameter nameValueDescription
call_signstringStation call sign (this is a unique value in our system)
full_common_namestringFull common name (Max: 255 characters)
short_common_namestringShort common name (Max: 128 characters)
tvss_urlstringThe URL of TV Schedule
donate_urlstringThe donation URL of the Station
timezonestringThe timezone of your Station's location
website_urlstringThe homepage URL of the Station
facebook_urlstringThe Facebook page of the Station
twitter_urlstringThe Twitter page of the Station
station_kids_urlstringThe kids homepage of the Station
telephonestringThe telephone number of the Station
faxstringThe fax number of the Station
citystringThe city in the station's mailing address.
statestringThe state in the station's mailing address.
address_line_1stringThe station's mailing address.
address_line_2stringThe station's mailing address.
zip_codestringThe zip code for the station's mailing address.
emailstringThe email contact of the Station
tag_linestringThe Station’s tag line
primary_channelstringDetermines the station’s default TV listings grid
primetime_startstringThe primetime start designated by the station.
imagesobject or empty listImages associated to a Station
updated_atdatetimeWhen the Station was last updated
idstringStation ID

The following table describes the parameters for all images.


Parameter nameValueDescription
profilestringThe profile of the image
urlstringThe link to the ITS image

Endpoints

Currently, Station is the only endpoint available in Station Manager. A station can be identified by its station ID (recommended) or by filtering by its flagship callsign (not recommended, as call signs change).

Base Endpoint
https://station.services.pbs.org/api/public/v1/stations/

Station:list

Returns a collection with all stations.

HTTP Request
GET https://station.services.pbs.org/api/public/v1/stations/


URI Parameters


Parameter nameValueDescription
[id]stringstation ID
call_signstringstation callsign (case sensitive). Must be ALL CAPS. This parameter is NOT RECOMMENDED, as call signs can change. We recommend using the station ID (shown above) instead.
pageintegerShow the results on a specific page.
sortstringShow the sorted by specific fields. The available fields are specified in the [‘meta’][‘sort’] block.

Example Output

The response for a request made to this endpoint will be paginated. The following response is for a request made without any query parameters:

Station information returned
{
  "meta": {
    "pagination": {
      "count": 176,
      "per_page": 25
    },
    "type": "collection",
    "filter": {
      "call_sign": "https://station.services.pbs.org/api/public/v1/stations/?call_sign="
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "attributes": {
        "call_sign": "KACV",
        "full_common_name": "Panhandle PBS",
        "short_common_name": "PPBS",
        "tvss_url": "http://www.panhandlepbs.org/schedule/#page=schedule&day=20150803&provider=Broadcast",
        "donate_url": "http://www.panhandlepbs.org/donate/",
        "timezone": "America/Chicago",
        "video_portal_url": "http://video.kacvtv.org",
        "website_url": "http://www.panhandlepbs.org/home/",
        "facebook_url": "https://www.facebook.com/KACVTV",
        "twitter_url": "http://twitter.com/PanhandlePBS",
        "station_kids_url": "",
        "passport_url": "https://kacv.secureallegiance.com/kacv/WebModule/Signon.aspx?P=CALLCENTER&PAGETYPE=PLG&CHECK=fiYWhgtNKHHv9jDXe9k%2f4L1YhDw50SikSh2nq0qouhg%3d",
        "telephone": "(806) 371-5222",
        "fax": "(806) 371-5258",
        "city": "Amarillo",
        "state": "TX",
        "address_line_1": "2408 S. Jackson",
        "address_line_2": "P.O. Box 447",
        "zip_code": 79178,
        "email": "PanhandlePBS@actx.edu",
        "tag_line": "",
        "primary_channel": "",
        "primetime_start": "7PM",
        "images": [
          {
            "url": "http://image.pbs.org/stations/kacv-black-logo-SU4Zh9o.png",
            "profile": "black-logo"
          },
          {
            "url": "http://image.pbs.org/stations/kacv-white-logo-KYRSwX8.png",
            "profile": "white-logo"
          },
          {
            "url": "http://image.pbs.org/stations/kacv-color-logo-uiSZViK.png",
            "profile": "color-logo"
          }
        ],
        "updated_at": "2016-12-06T14:22:24.701762Z"
      },
      "links": {
        "self": "https://station.services.pbs.org/api/public/v1/stations/838f7279-cacf-4561-bd33-ac9a4b1429e8/"
      },
      "id": "838f7279-cacf-4561-bd33-ac9a4b1429e8",
      "type": "station"
    },
    {
      "attributes": {
        "call_sign": "KAET",
        "full_common_name": "Arizona PBS",
        "short_common_name": "ArizonaPBS",
        "tvss_url": "http://www.azpbs.org/schedule",
        "donate_url": "http://www.azpbs.org/support/donate.php",
        "timezone": "America/Phoenix",
        "video_portal_url": "http://video.azpbs.org",
        "website_url": "http://www.azpbs.org",
        "facebook_url": "https://www.facebook.com/arizonapbs",
        "twitter_url": "https://twitter.com/arizonapbs",
        "station_kids_url": "",
        "passport_url": "http://kaet.convio.net/site/Donation2?df_id=14065&mfc_pref=T&14065.donation=form1",
        "telephone": "(602) 496-8888",
        "fax": "(602) 496-8045",
        "city": "Phoenix",
        "state": "AZ",
        "address_line_1": "Arizona PBS/KAET-TV",
        "address_line_2": "555 North Central Avenue, Suite 500",
        "zip_code": 85004,
        "email": "",
        "tag_line": "",
        "primary_channel": "Arizona PBS",
        "primetime_start": "7PM",
        "images": [
          {
            "url": "http://image.pbs.org/stations/kaet-black-logo-hCQbMES.png",
            "profile": "black-logo"
          },
          {
            "url": "http://image.pbs.org/stations/kaet-white-logo-Llx4O7Q.png",
            "profile": "white-logo"
          },
          {
            "url": "http://image.pbs.org/stations/kaet-color-logo-cY7tFGf.png",
            "profile": "color-logo"
          }
        ],
        "updated_at": "2016-12-05T17:09:16.908590Z"
      },
      "links": {
        "self": "https://station.services.pbs.org/api/public/v1/stations/6d08b852-2c19-4eb7-9348-a5e15b685357/"
      },
      "id": "6d08b852-2c19-4eb7-9348-a5e15b685357",
      "type": "station"
    },


Filter by Station ID

Requesting the station that will match WETA station ID. This will always return 1 or 0 results, because the filtering is an exact match by ID.

How Do I Get Station ID?

Look up the station ID using the link below, and appending the station flagship call sign to the end. In the response, look for the "id" field. Use this id value to Filter by Station ID, which is the recommended way to request station data. (This is because call signs can change; the ID will never change.) The example below uses WETA:

https://station.services.pbs.org/api/public/v1/stations/?call_sign=WETA

Filter by Station ID
 https://station.services.pbs.org/api/public/v1/stations/92d89794-5ff0-4fe6-a443-cc888104e021
Station information returned
{
  "data": {
    "type": "station",
    "id": "92d89794-5ff0-4fe6-a443-cc888104e021",
    "attributes": {
      "call_sign": "WETA",
      "full_common_name": "WETA",
      "short_common_name": "WETA",
      "tvss_url": "http://www.weta.org/schedule",
      "donate_url": "http://support.weta.org/pbs",
      "timezone": "America/New_York",
      "video_portal_url": "http://watch.weta.org",
      "website_url": "http://www.weta.org",
      "facebook_url": "http://facebook.com/wetatvfm",
      "twitter_url": "http://twitter.com/wetatvfm",
      "station_kids_url": "http://www.weta.org/kids",
      "passport_url": "http://support.weta.org/passport",
      "telephone": "(703) 998-2724",
      "fax": "(703) 998-3401",
      "city": "Arlington",
      "state": "VA",
      "address_line_1": "3939 Campbell Avenue",
      "address_line_2": "",
      "zip_code": 22206,
      "email": "audienceservices@weta.org",
      "tag_line": "Public television and classical music for Greater Washington",
      "primary_channel": "WETA TV",
      "primetime_start": "8PM",
      "images": [
        {
          "profile": "black-logo",
          "url": "http://image.pbs.org/stations/weta-black-logo-fgPrvsK.png"
        },
        {
          "profile": "white-logo",
          "url": "http://image.pbs.org/stations/weta-white-logo-JQgQDpP.png"
        },
        {
          "profile": "color-logo",
          "url": "http://image.pbs.org/stations/weta-color-logo-iZbJH8k.png"
        }
      ],
      "updated_at": "2016-12-06T14:42:24.139513Z"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "type": "resource"
  },
  "links": {
    "self": "https://station.services.pbs.org/api/public/v1/stations/92d89794-5ff0-4fe6-a443-cc888104e021/"
  }
}

HTTP Response Status Codes

The possible Status codes returned by this call are 200, 401, 403, 500. For information about these statuses, refer to the HTTP response status codes section.


HTTP Request Headers

The header ‘Content-type’ should have the value ‘application/json’ as described in HTTP Request headers.

HTTP Response Status Codes

The following are possible status codes returned by API calls responses.

 

Status codeMeaningResolution
200SuccessOperation was successful
400Bad requestDescription of the error will be given in the payload
401Unauthenticated consumerThe consumer with this key:secret pair doesn’t exist in the system
403Unauthorized consumerThe consumer with the key:secret doesn’t have access to this resource
404No resources foundThe demanded resources can not be found
500Internal server errorUnknown error

 

"timezone": "America/Chicago",

Pagination

The Station Manager API uses "page-size" to determine the number of results displayed on one page. The maximum allowed number of results that you can display is 50. 

The following is an example returning three stations.

Pagination example
https://station.services.pbs.org/api/public/v1/stations/?page-size=3

Select page

The Station Manager API uses "page=" to determine which page of results you wish to view. If you have 10 pages of results, you can use this filter to jump to page two, or any other page within the 10 results.

The following is an example of jumping to page two of the list of results for stations. 

Select page example
https://station.services.pbs.org/api/public/v1/stations/?page=2