API Documentation

The PIN offers a number of APIs, known under the umbrella name of the Publishing API, for pushing and pulling data into and out of the Network. This page describes the Publishing API and how to use it.

Overview

The PIN data model revolves around a few primary objects: Queries, Submissions and Sources.

A Query is a set of questions and related information like author names and introductory text.

A Submission is a set of responses to the questions in a Query.

A Source is the person who shares a Submission with the PIN.

Each object is uniquely identified with a 12-character string we call a UUID. The UUID can be used to address and search for specific objects with our APIs.

Query API

The Query API allows you to embed PIN queries on a secure (https) web page and to submit responses to those queries. Here’s an example of the Javascript code for embedding a Query with the UUID abcdef123456 on a web page:

  <div id="pin-query-abcdef123456"></div>
 <!-- jquery should be uncommented if your site does not run jquery otherwise delete these 2 lines -->
 <!-- script type="text/javascript" src="https://www.publicinsightnetwork.org/source/js/jquery-1.8.1.min.js" --></script>
 <script type="text/javascript" src="https://www.publicinsightnetwork.org/air2/js/pinform.js"></script>
 <script type="text/javascript">
     var PIN_QUERY = {
       uuid: 'abcdef123456',
       divId: 'pin-query-abcdef123456',
       opts: {
           includeLegalFooter: true,
           validationErrorMsg: 'Sorry, you have problems!',
           showIntro: false,

           // the thankYou callback is invoked after the Submit button is clicked
           thankYou: function(divId, respData) {
               var div = jQuery('#'+divId);
               var queryMeta = PIN.Form.Registry[divId];
               div.text('Thanks! Your submission is ' + respData.uuid);
           },

           // the onRender callback is invoked after the query HTML is built.
           onRender: function(divId, queryData) {
               var div = jQuery('#'+divId);
               div.prepend('

'+queryData.query.inq_ext_title+'

'); } } }; jQuery(document).ready(function() { PIN.Form.render(PIN_QUERY) }); </script>

Query API Details

The embedded query displays a form and handles the form submission via an AJAX pattern. This section describes some of the details of the API.

You can fetch the JSON for the example Query:

GET https://www.publicinsightnetwork.org/air2/q/abcdef123456.json

The JSON response looks like:

 {
  "authors": [
   {
     "email" : "author@example.foo",
     "first" : "Susan",
     "last"  : "Journalist"
   },
  ],
  "query": {
    "inq_uuid" : "abcdef123456",
    "inq_ext_title" : "Tell us about your favorite recipe",
  },
  "questions" : [
    {
      "ques_uuid" : "er7MYfe60IAi",
      "ques_value" : "What ingredients are in your favorite recipe?"
    }
  ],
  "action" : "https://www.publicinsightnetwork.org/air2/q/abcdef123456",
  "method" : "POST"
 }

You can POST a submission to the example Query at the action value

POST https://www.publicinsightnetwork.org/air2/q/abcdef123456
er7MYfe60IAi=salt%20pepper

where the body of the request is a set of key/value pairs, each key being the ques_uuid for a question in the Query.

Submission API

To use the Submission API you must first request an API key. The API key is used to identify your use of the API and to help us improve it. Currently, only existing journalists who work for contracted PIN partners are eligible to receive API keys.

Once you have a key, you can use it with the example widget below to embed Submissions on a web page:

 <div id="insight-feed"></div>
 <a href="#" id="loadmore">Load More</a>
 <!-- jquery should be uncommented if your site does not run jquery otherwise delete these 2 lines -->
 <!-- script type="text/javascript" src="https://www.publicinsightnetwork.org/source/js/jquery-1.8.1.min.js" --></script>
 <script type="text/javascript" src="https://www.publicinsightnetwork.org/source/js/insights.js"></script>
 <script type="text/javascript">
     jQuery(document).ready(function() {
        PIN.Insights.widget({
            where:      'query_uuid:abcdef123456',  // search string (required)
            apiKey:     'your-api-key-here',        // API key (required)
            divId:      'insight-feed',             // your DOM id (default: insight-feed)
            pageSize:   25,                         // paging size (default: 25)
            loadMore:   'loadmore'                  // your DOM id (optional)
        });
    });
 </script>

Submission API Details

The Insights widget example above will embed a page-able list of all the submissions for a specific Query UUID. The where parameter is similar to a SQL WHERE clause. You can pass in key/value pairs or even bare keywords for full-text search.

The supported search fields and other API metadata can be found in JSON format at the API “about” URL.

Examples include:

find all the submissions with a last name of “smith”
src_last_name:smith
find all the submissions in the state of Minnesota
state:MN
find all the submissions in Ramsey county
county:Ramsey
find all the submissions from April, 2013
srs_date:201304*
find all the submissions from within a latitude/longitude range*
latitude:(134.000000..135.000000) AND longitude:(086.000000..087.000000)
* Note that latitude and longitude are normalized from signed floats to fixed-width strings in the search engine. To convert from 44.8947 lat -93.2519 long, add 180 to the longitude and and 90 to the latitude, and make sure to initial-pad with zeros to reach 10 total characters.

$latitude = 44.8947;
$longitude = -93.2519;
$norm_latitude = sprintf("%010.6f", $latitude + 90.0);     // 134.894700
$norm_longitude = sprintf("%010.6f", $longitude + 180.0);  // 086.748100

You can also access the API directly at

GET https://www.publicinsightnetwork.org/air2/api/public/search

where the URL GET parameters are:

a (required)
Your API key
q (required)
The search ‘where’ clause
t (default ‘JSON’)
The response format (JSON, XML, ExtJS, Tiny)
s (optional)
The sort order. You may sort by any response field, in either ASC (default) or DESC direction.
x (optional)
Return a subset of response fields

You can read more about the search API in the Search::OpenSearch documentation.