Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
maxLevel3

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. 


Panel
titleOther topics


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.
  • Basic Authentication HTTP Protocol. To use the API, Basic authentication will have to be used. A short reference can be found in the  Authentication section.

 


Authentication

Note

To obtain authentication credentials please contact your PBS station representative. You can also make calls using our public API which does not require authentication.

In order to access exposed resources, an API consumer needs to be assigned to a Group that is assigned to a specific Station.  The protocol for authentication is Basic Auth as defined by the Internet Engineering Task Force, in the Request for Comments number 2617 ( http://www.rfc-editor.org/rfc/rfc2617.txt ). In order to use this API, Basic Auth protocol must be used.

An API Consumer is defined by a key (example: john) and a secret (example: mypassword). The key and secret are similar to a username and password and both must be provided to users of the API. An API Consumer will have a set of operations that it can execute. For example, one API Consumer will be able to only read data, but another API consumer will be able to also modify the data.

All requests must contain the header Authorization, which contains the name of the authentication method (Basic), followed by a base64 encoded string of type key:secret.

Panel
titleExample

For key = 'john' and secret = 'password' - Authorization: Basic = am9objpteXBhc3N3b3Jk

To obtain am9objpteXBhc3N3b3Jk, we took the string  john:mypassword  and used a tool like  http://www.base64encode.org/  to encode it.

Authorization

The authorization section handles configuration needed for the API consumer to have the right to access/edit certain resources. In order for an API consumer to have access to the exposed resources, it needs to be assigned to a Group that has a specific Station assigned.

For the resources that are currently exposed, namely the station, the Group that the consumer was assigned to also needs to have assigned to it the Permission to change the specific resource (i.e.: change the current station).

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.
listRetrieves (GET) a list of zero or more resources.
createRetrieves (POST) a list of zero or more resources.
updateModifies (PUT/PATCH) an existing resource to reflect data in your request.

 


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 typegetlistupdatecreate
Station yesyesyesyes

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
short_common_namestringShort common name
tvss_urlstringThe URL of TV Schedule
donate_urlstringThe donation URL of the Station
kids_live_stream_urlstringThe URL of your KIDS livestream
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
passport_urlstringThe passport page of the Station
telephonestringThe telephone number of the Station
faxstringThe fax number of the Station
pdpboolProgram Differentiation Plan (PDP) of the Stations
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
passport_enabledboolWether or not the station is Passport Enabled
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

 


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 or by filtering by its flagship callsign. 

Code Block
titleBase Endpoint
https://station.services.pbs.org/api/v1/stations/ 

Station:list

Returns a collection with all stations.

Code Block
titleHTTP Request
GET https://station.services.pbs.org/api/v1/stations/

 


URI Parameters

 


Parameter nameValueDescription
call_signstringstation callsign (case sensitive). Must be ALL CAPS.
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:

Code Block
titleStation information returned
{
  "links": {
    "prev": null,
    "self": "https://station.services.pbs.org/api/v1/stations/",
    "first": "https://station.services.pbs.org/api/v1/stations/",
    "next": "https://station.services.pbs.org/api/v1/stations/?page=2",
    "last": "https://station.services.pbs.org/api/v1/stations/?page=8"
  },
  "data": [
    {
      "links": {
        "self": "https://station.services.pbs.org/api/v1/stations/838f7279-cacf-4561-bd33-ac9a4b1429e8/"
      },
      "id": "838f7279-cacf-4561-bd33-ac9a4b1429e8",
      "type": "station",
      "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/",
        "kids_live_stream_url": "http://live.pbskids.org/out/u/est.m3u8",
        "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",
        "pdp": false,
        "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": "",
        "passport_enabled": true,
        "primary_channel": "",
        "primetime_start": "7PM",
        "images": [
          {
            "profile": "black-logo",
            "url": "http://image.pbs.org/stations/kacv-black-logo-SU4Zh9o.png"
          },
          {
            "profile": "white-logo",
            "url": "http://image.pbs.org/stations/kacv-white-logo-KYRSwX8.png"
          },
          {
            "profile": "color-logo",
            "url": "http://image.pbs.org/stations/kacv-color-logo-uiSZViK.png"
          }
        ],
        "updated_at": "2016-12-06T14:22:24.701762Z"
      }
    },

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

Code Block
titleFiltering by flagship callsign
 https://station.services.pbs.org/api/v1/stations/?call_sign=WETA


Code Block
titleStation information returned
{
  "meta": {
    "sort": {
      "call_sign": {
        "asc": "https://station.services.pbs.org/api/v1/stations/?sort=call_sign",
        "desc": "https://station.services.pbs.org/api/v1/stations/?sort=-call_sign"
      },
      "short_common_name": {
        "asc": "https://station.services.pbs.org/api/v1/stations/?sort=short_common_name",
        "desc": "https://station.services.pbs.org/api/v1/stations/?sort=-short_common_name"
      }
    },
    "filter": {
      "call_sign": "https://station.services.pbs.org/api/v1/stations/?call_sign="
    },
    "type": "collection",
    "pagination": {
      "per_page": 25,
      "count": 1
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "prev": null,
    "first": null,
    "last": null,
    "self": "https://station.services.pbs.org/api/v1/stations/?call_sign=WETA",
    "next": null
  },
  "data": [
    {
      "id": "92d89794-5ff0-4fe6-a443-cc888104e021",
      "type": "station",
      "links": {
        "self": "https://station.services.pbs.org/api/v1/stations/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",
        "kids_live_stream_url": "http://live.pbskids.org/out/u/est.m3u8",
        "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",
        "pdp": false,
        "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",
        "passport_enabled": true,
        "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"
      }
    }
  ]
}

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.

Station:get

Returns the station entity matching {id}.

Code Block
titleHTTP Request
GET https://station.services.pbs.org/api/v1/stations/{id}/ 

URL Parameters

 


Example output

Code Block
titleStation information returned
{
  "meta": {
    "type": "resource"
  },
  "links": {
    "self": "https://station.services.pbs.org/api/v1/stations/838f7279-cacf-4561-bd33-ac9a4b1429e8/"
  },
  "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/",
      "kids_live_stream_url": "http://live.pbskids.org/out/u/est.m3u8",
      "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",
      "pdp": false,
      "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": "",
      "passport_enabled": true,
      "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"
    },
    "type": "station",
    "id": "838f7279-cacf-4561-bd33-ac9a4b1429e8"
  }
}

 


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
Panel
titleOther topics