NYSenate.gov Application Protocol Interface (API)

The New York State Senate provides an application programming interfaces (API) through which external computers and websites can retrieve information about Senators, committees, legislation, meetings and other Senate-related events. This page is intended to document how the API works.

Services

NYSenate.gov is powered by the Drupal open-source content management system and uses the Services module for Drupal to provide information using its XML-RPC and JSON servers. To access information using the Services module, you will need to apply for an individual API key by visiting http://www.nysenate.gov/developers/request_api_key.

Once your request has been approved, we will email you an API key which contains two pieces of information:

  1. A randomized string, such as '9e3g1aab8829bd19da43c76b4460b26f'.
  2. A domain to be associated with that string, such as 'www.mysite.com'.

To access a service, you submit a request to a specified URL or "endpoint." Those URLs, for JSON and XML-RPC respectively, are as follows:

  • http://www.nysenate.gov/services/json
  • http://www.nysenate.gov/services/xmlrpc

We have created a PHP library to simplify the process of accessing the XML-RPC server, along with some sample code showing examples of how it works. You can download the PHP library by visiting our source code for developers page.

The JSON and XML-RPC servers both allow retrieval of information using two methods: node.get and views.get. To understand these methods, it helps to first understand the meaning of the terms "node" and "view."

Nodes

A node is a primary unit of content within Drupal, the content management system that runs NYSenate.gov. Nodes come in a variety of different "content types." Each blog post, for example, is considered a separate node with a content type of 'blog' and a unique numerical node ID. In addition to blogs, NYSenate.gov has defined other content types including "senator," "committee," "district," "event," "testimony," "photo" and "video." Just as each blog post is a separate node with its own unique node ID, each event is also stored and handled by Drupal as a separate node, only with "event" rather than "blog" as its content type. Similarly, each committee is a node of content type "committee." For a listing of available content types and the information that can be retrieved from each, visit our content types documentation.

Each node's unique node ID (nid) can be used to retrieve information specific to that node. For example, nid 107 refers to a node of content type "senator" with the information specific to Senator Eric Adams. To retrieve information about Senator Adams, therefore, you would send a node.get request for nid 107. If you use our PHP library to send that request, the code to do so would be as follows:

<?php
  include('xmlrpc-api.inc');
  $api_key        = ''; // your API key here
  $domain_name    = ''; // your domain name here

  $service = new nodeGet($domain_name, $api_key);
  $values = $service->get(array(
    'nid' => 107,
  ));
  print var_dump($values);
?>

Each content type has a number of predefined fields. If you only want to retrieve some of those fields, you can specify the ones you ant using by including a "fields" parameter when you submit the node.get request. The following example would retrieve only Senator Adams' name (the "title" field) and his office address (the "field_location" field).

<?php
  include('xmlrpc-api.inc');
  $api_key        = ''; // your API key here
  $domain_name    = ''; // your domain name here

  $service = new nodeGet($domain_name, $api_key);
  $values = $service->get(array(
    'nid' => 107,
    'fields' => array('title', 'field_location'),
  ));
  print var_dump($values);
?>

For a listing of the fields that are available for senators and for other content types, visit our content types documentation.

Views

For a listing of views and their displays that can be retrieved from NYSenate.gov, visit our views documentation page.

The Views module in Drupal is basically a report builder. It can be used to build lists (including complex lists) of information, which then get represented in a variety of layouts and formats. NYSenate.gov uses more than a hundred custom views. Examples include:

As the searchable video archive listed above illustrates, views can have filter forms that select what items to include in the listing. They can also receive arguments that specify what should appear in the listing. For the Aging committee page referenced above, "Aging" is an argument, which Views retrieves by parsing the page's URL.

View Names and Display Names

In order to retrieve information from Drupal views, you need to know how to specify that information by view name and display name. The distinction between "views" and "displays" can seem a bit confusing at first, so we'll explain it here.

Each Drupal view is identified by a unique view name — a string that consists of alphanumeric characters and underscores. In the examples listed above, the view names are "senators", "global_calendar", "video" and "committee_updates." Each view includes a default display and possibly includes other displays as well, which may override parts of the default display. For example, the calendar of events contains separate displays that list all events for a specified month, all events for a specified week, all events for a specified day, etc. Each of these displays is based partially on the default display for view "global_calendar" while overriding some of the settings inherited from the default view.

Each display of a view has its own unique display name, which is usually assigned automatically by the Views module based on its display type. The default display of a view is always named "default." Some displays are of type "page," meaning that they are intended to display their content in the main content area of standalone pages. Displays of this type are given names consisting of "page_" followed by an integer: "page_1," "page_2," etc. There are also "block" displays that are intended to display their content as sidebar blocks within the site layout. These views have names consisting of "block_1," block_2," etc. Blocks and views are the most common display types, but there are others as well, e.g., "feed_1," "calendar_1."

For a listing of views and their displays that can be retrieved from NYSenate.gov, visit our views documentation page.

Retrieving Views Information via the Services API

Once you have identified the view name and display name that you want to retrieve, the Services API for views works similarly to the Services API for nodes. Here are some examples:

Get the node ID (nid) and title for all committees

<?php
  include('xmlrpc-api.inc');
  $api_key        = ''; // your API key here
  $domain_name    = ''; // your domain name here
  $service = new viewsGet($domain_name, $api_key);
  $values = $service->get(array(
    'view_name' => 'committees',
  ));
  print var_dump($values);
?>

Get the node ID (nid) and title for all temporary committees

<?php
  include('xmlrpc-api.inc');
  $api_key        = ''; // your API key here
  $domain_name    = ''; // your domain name here
  $service = new viewsGet($domain_name, $api_key);
  $values = $service->get(array(
    'view_name' => 'committees',
    'display_id' => 'page_2',
  ));
  print var_dump($values);
?>

Get the node ID (nid) and title for the first two committees

<?php
  include('xmlrpc-api.inc');
  $api_key        = ''; // your API key here
  $domain_name    = ''; // your domain name here
  $service = new viewsGet($domain_name, $api_key);
  $values = $service->get(array(
    'view_name' => 'committees',
    'limit' => 2,
  ));
  print var_dump($values);
?>

Get a list of all committees, formatted as HTML

<?php
  include('xmlrpc-api.inc');
  $api_key        = ''; // your API key here
  $domain_name    = ''; // your domain name here
  $service = new viewsGet($domain_name, $api_key);
  $values = $service->get(array(
    'view_name' => 'committees',
    'format_output' => TRUE,
  ));
  print var_dump($values);
?>

Get the last 5 senator news items for Eric Adams

<?php
  include('xmlrpc-api.inc');
  $api_key        = ''; // your API key here
  $domain_name    = ''; // your domain name here
  $service = new viewsGet($domain_name, $api_key);
  $values = $service->get(array(
    'view_name' => 'senator_news',
    'display_id' => 'block_1',
    'args' => array('Eric Adams'),
    'limit' => 5,
  ));
  print var_dump($values);
?>

Get the district map for Eric Adams

<?php
  include('xmlrpc-api.inc');
  $api_key        = ''; // your API key here
  $domain_name    = ''; // your domain name here
  $service = new viewsGet($domain_name, $api_key);
  $values = $service->get(array(
    'view_name' => 'district_map',
    'args' => array('106'),
  ));
  print var_dump($values);
?>

Additional Resources

The Drupal website has further documentation on the Services module, including code samples, at these URLs: