API V1 Documentation

[iSENSE]

Client-side API examples are available on Github.

Please note: All requests must use HTTPS. HTTP requests are no longer supported.

Click on an API request to expand documentation.

GET Projects /api/v1/projects/(project id) id(req) recur(opt boolean)

Get properties of a project.

Response Codes
  • Success: 200 OK
  • Fail: 404 Not Found
Example (Javascript)
    var urlProject = 'https://isenseproject.org/api/v1/projects/(project id)';

    var responseProject = $.ajax({ type: "GET",
                                    url: urlProject,
                                  async: false,
                               dataType: "JSON"
    }).responseText;

    var parsedResponseProject = JSON.parse(responseProject);

    console.log(parsedResponseProject);
          
Response
    {
      "id"=> ID of project (integer),
      "featuredMediaId"=> ID of associated picture (integer),
      "name"=> Project name (string),
      "url"=> URL of project (string),
      "path"=> Project path (string),
      "hidden"=> Visibility (boolean),
      "featured"=> Featured status (boolean),
      "likeCount"=> Number of likes (boolean),
      "content"=> HTML safe description (text),
      "timeAgoInWords"=>"less than a minute",
      "createdAt"=>"January 28, 2014",
      "ownerName"=> Name of project owner (string),
      "ownerUrl"=> URL of project owners profile (string),
      "dataSetCount"=> Number of associated data sets (integer),
      "dataSetIDs" => ID's of all data sets (integer)
      "fieldCount" => Number of contained fields (integer),
      "fields" => Fields associated with project (array),
      "formulaFieldCount" => Number of contained formula fields (integer),
      "formulaFields" => Formula fields associated with project (array)
    }
          
Notes
  • If recur is set to true, the function will also return 'dataSets', 'mediaObjects', and 'owner' objects
GET Projects /api/v1/projects search(opt), sort(opt), order(opt), per_page(opt), page(opt), search(opt), templates_only(opt), curated_only(opt), featured_only(opt), has_data(opt)

Get an array of all the projects.

Response Codes
  • Success: 200 OK
Example (Javascript)
    var urlProject = 'https://isenseproject.org/api/v1/projects';
    var responseProject = $.ajax({ type: "GET",
                                    url: urlProject,
                                  async: false,
                               dataType: "JSON" }).responseText;

    var parsedResponseProject = JSON.parse(responseProject);

    console.log(parsedResponseProject);
          
Response
    {
      "Projects"=> (array)
    }
          
Notes
  • search - id or string
  • sort - "like_count", "views, "created_at", "updated_at" (default updated_at)
  • order - "ASC", "DESC" (default "DESC")
  • per_page - integer (default 50)
  • page - integer (default 1)
  • Including the templates_only, curated_only, featured_only, or has_data keys will filter the results accordingly. The value passed along with the key is irrelevant.
POST Projects /api/v1/projects email(req), password(req), project_name(opt)

Create a new project.

Response Codes
  • Success: 200 OK
  • Fail: 401 Unauthorized
  • Fail: 422 Unprocessable Entity
Data
  {
    "email" => "email address (string)",
    "password" => "password (string)",
    "project_name" => (string)
  }
          
Example (Javascript)
    var apiUrl = 'https://isenseproject.org/api/v1/projects';

    var upload = {
        'email': '(email)',
        'password': '(password)',
        'project_name': '(project name)',
    }

    $.post(apiUrl, upload);
          
Response
  {
    "id"=> ID of project (integer),
    "featuredMediaId"=> ID of associated picture (integer),
    "name"=> Project name (string),
    "url"=> URL of project (string),
    "path"=> Project path (string),
    "hidden"=> Visibility (boolean),
    "featured"=> Featured status (boolean),
    "likeCount"=> Number of likes (boolean),
    "content"=> HTML safe description (text),
    "timeAgoInWords"=>"less than a minute",
    "createdAt"=>"January 28, 2014",
    "ownerName"=> Name of project owner (string),
    "ownerUrl"=> URL of project owners profile (string),
    "dataSetCount"=> Number of associated data sets (integer),
    "fieldCount"=> Number of contained fields (integer),
    "fields"=> Fields associated with project (array)
  }
          
Notes
  • If a name is not given, one will be generated based on the user's name.
POST Projects /api/v1/projects/(project id)/add_key email(req), password(req), project_name(opt)

Create a new key for an existing project.

Response Codes
  • Success: 201 Created
  • Fail: 401 Unauthorized
  • Fail: 409 Conflict
  • Fail: 422 Unprocessable Entity
Data
    {
        "email" => "email address (string)",
        "password" => "password (string)",
        "contrib_key" => {  'name' => "Key's Name(string)",
                            'key' => "Key (string)"
                         }
    }
          
Example (Javascript)
    var apiUrl = 'https://isenseproject.org/api/v1/projects/(project id)/add_key';

    var upload = {
        'email' : '(email)',
        'password' : '(password)',
        'contrib_key': {  'name' : '(key name)',
                          'project_id' : (project id),
                          'key' : '(key)'
                        }
    }

    $.post(apiUrl, upload);
          
Response
    {
        "msg" => "Success or error message. (String)"
    }
          
Notes
  • The user must be the owner of the project.

GET Key /api/v1/projects/(project id)/key/ contribution_key(req)
Response Codes
  • Success: 302 Found
  • Fail: 404 Not Found
Data
  {
    "contribution_key" => "contribution key (string)"
  }
          
Example (Javascript)
    var url = 'http://isenseproject.org/api/v1/projects/(project id)/key';
    var response = $.ajax({ type: "GET",
                             url: url,
                           async: false,
                        dataType: "JSON",
                           data : {"contribution_key":"(key)"}
    }).responseText;

    var parsedResponse = JSON.parse(response);
    console.log(parsedResponse);
          
Response
  {
    "contribution_key": "(string)"
  }
          
Notes
  • N/A

POST Fields /api/v1/fields email(req), password(req), project_id(req), field_type(req), name(opt), units(opt), restrictions(opt)

Add a new field to a project.

Response Codes
  • Success: 200 OK
  • Fail: 401 Unauthorized
  • Fail: 422 Unprocessable Entity
Data
  {
    "email" => "email address (string)",
    "password" => "password (string)",
    "field" =>  {
                  "project_id" =>  integer,
                  "field_type" =>  integer,
                  "name" => string,
                  "unit" => string,
                  "restrictions" => string
                }
  }

          
Example (Javascript)
    var apiUrl = 'https://isenseproject.org/api/v1/fields';

    var upload = {
        'email' : '(email)',
        'password' : '(password)',
        'field' : { 'project_id' : (project id),
                    'field_type' : (1, 2, 3, 4, or 5),
                    'name' : '(field name)',
                    'unit' : '(field's unit of measurement)',
                    'restrictions': '(restriction1, restriction2, restriction3)' # optional
                  }
    }

    $.post(apiUrl, upload);
          
Response
  {
    "id"=> Field ID (integer),
    "name"=> Field name (string),
    "type"=> Field type (integer),
    "unit"=> Field units (string),
    "restrictions"=> Accepted Values(string)
  }

          
Notes
  • The user must be the owner of the project.
  • Names - Must be unique per project. If name is not set one will be given based on type.
  • Units - e.g. meters, lumens (ignored for timestamp and text)
  • type - 1=Timestamp 2=Number 3=Text 4=Latitude 5=Longitude (lat/lon are created together)
  • restrictions - Currently only applys to text fields. If we define restrictions for "blue,green,red" the project will only accept those strings for that field
GET Fields /api/v1/fields/(field id) id(req)

Get properties of a field.

Response Codes
  • Success: 200 OK
  • Fail: 404 Not Found
Example (Javascript)
    var urlProject = 'https://isenseproject.org/api/v1/fields/(field id)';

    var responseProject = $.ajax({ type: "GET",
                                    url: urlProject,
                                  async: false,
                               dataType: "JSON"
    }).responseText;

    var parsedResponseProject = JSON.parse(responseProject);


    console.log(parsedResponseProject);

    $.post(apiUrl, upload);
          
Response
  {
    "id"=> Field ID (integer),
    "name"=> Field name (string),
    "type"=> Field type (integer),
    "unit"=> Field units (string),
    "restrictions"=> Accepted Values(string)
  }
          
Notes
  • The user must be the owner of the project.

GET Data Sets /api/v1/data_sets/(data set id)/ id(req)

Get properties of a data set.

Response Codes
  • Success: 200 OK
  • Fail: 404 Unprocessable Entity
Example (Javascript)

  var url = 'https://isenseproject.org/api/v1/data_sets/(data set id)';
  var response = $.ajax({ type: "GET",
                           url: url,
                         async: false,
                      dataType: "JSON"
  }).responseText;

  var parsedResponse = JSON.parse(response);
  console.log(parsedResponse);
          
Response
   {
    "id"=> Data Set ID (integer),
    "name"=> Data Set Title (string),
    "url"=> Visualization URL (string),
    "path"=> Data Set Path (string),
    "createdAt"=>"January 28, 2014",
    "fieldCount"=> Number of fields (integer),
    "datapointCount"=> Number of data points (integer),
    "displayURL"=> Display URL (string)
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }
    }
          
Notes
  • N/A
POST Data Sets /api/v1/projects/(project id)/jsonDataUpload email(req), password(req), title(req), data(req)

Upload a data set in the form of JSON with a username and password.

Response Codes
  • Success: 200 OK
  • Fail: 401 Unauthorized
  • Fail: 422 Unprocessable Entity
Data
  {
    "email" => "email address (string)",
    "password" => "password (string)",
    "title" => (string),
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }

  }
          
Example (Javascript)
    var apiUrl = 'https://isenseproject.org/api/v1/projects/(project id)/jsonDataUpload';

    var upload = {
        'email' : '(email)',
        'password' : '(password)',
        'title' : '(title)',
        'data' :  {
                    '(field id)'   : [1,2,3],
                    '(field id_2)' : ["blue", "red", "green"]
                  }
    }

    $.post(apiUrl, upload);
          
Response
  {
    "id"=> Data Set ID (integer),
    "name"=> Data Set Title (string),
    "hidden"=> Visibility (boolean),
    "url"=> Visualization URL (string),
    "path"=> Data Set Path (string),
    "createdAt"=>"January 28, 2014",
    "fieldCount"=> Number of fields (integer),
    "datapointCount"=> Number of data points (integer),
    "displayURL"=> Display URL (string)
  }
          
Notes
  • A user can upload data to any unlocked project.
  • Data is a hash of field_id -> data array pairs. FIELD_ID and FIELD_ID_2 would be replaced with ids for their respective fields.
POST Data Sets /api/v1/projects/(project id)/jsonDataUpload contribution_key(req), contributor_name(req), data(req)

Upload a data set in the form of JSON with a contribution key. Keys can be added to a project by the owner.

Response Codes
  • Success: 200 OK
  • Fail: 401 Unauthorized
  • Fail: 422 Unprocessable Entity
Data
  {
    "title" => "Title for the data set (string)"
    "contribution_key" => "key created by project owner (string)",
    "contributor_name" => (string),
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }

  }
          
Example (Javascript)
    var apiUrl = 'https://isenseproject.org/api/v1/projects/(project id)/jsonDataUpload';

    var upload = {
        'title' : '(title)',
        'contribution_key' : '(key)',
        'contributor_name' : '(Your name)',
        'data' :  {
                    '(field id)' : [1,2,3]
                  }
    }

    $.post(apiUrl, upload);
          
Response
  {
    "id"=> Data Set ID (integer),
    "name"=> Data Set Title (string),
    "hidden"=> Visibility (boolean),
    "url"=> Visualization URL (string),
    "path"=> Data Set Path (string),
    "createdAt"=>"January 28, 2014",
    "fieldCount"=> Number of fields (integer),
    "datapointCount"=> Number of data points (integer),
    "displayURL"=> Display URL (string)
  }
          
Notes
  • Data is a hash of field_id -> data array pairs. FIELD_ID and FIELD_ID_2 would be replaced with ids for their respective fields.
GET Data Sets /api/v1/data_sets/(data set id)/edit email(req), password(req), id(req)

Edit an existing data set with a username and password.

Response Codes
  • Success: 200 OK
  • Fail: 401:Unauthorized
  • Fail: 404 Not Found
  • Fail: 422 Unprocessable Entity
Data
  {
    "email" => "email address (string)",
    "password" => "password (string)",
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }

  }
          
Example (Javascript)
    var apiUrl = 'https://isenseproject.org/api/v1/data_sets/(data set id)/edit';

    var upload = {
        'email' : '(email)',
        'password' : '(password)',
        'data' :  {
                    '(field id)' : [1,5,6]
                  }
    }

    $.get(apiUrl, upload);
          
Response
  {
    "id"=> Data Set ID (integer),
    "name"=> Data Set Title (string),
    "hidden"=> Visibility (boolean),
    "url"=> Visualization URL (string),
    "path"=> Data Set Path (string),
    "createdAt"=>"January 28, 2014",
    "fieldCount"=> Number of fields (integer),
    "datapointCount"=> Number of data points (integer),
    "displayURL"=> Display URL (string)
  }
          
Notes
  • A user can edit any data set that they have uploaded or any data set that is on a project that he/she owns.
  • Setting recur=true as a get variable will return the associated Project(hash), Fields(hash), Data(hash)
GET Data Sets /api/v1/data_sets/(data set id)/edit contribution_key(req), id(req)

Edit an existing data set with a contribution key. The data set must have been uploaded with the same contribution key.

Response Codes
  • Success: 200 OK
  • Fail: 401:Unauthorized
  • Fail: 404 Not Found
  • Fail: 422 Unprocessable Entity
Data
  {
    "contribution_key" => "a contribution key (string)",
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }

  }
          
Example (Javascript)
    var apiUrl = 'https://isenseproject.org/api/v1/data_sets/(data set id)/edit';

    var upload = {
        'contribution_key' : '(key)',
        'data' :  {
                    '(field id)' : [1,2,3,4]
                  }
    }
    $.get(apiUrl, upload);
          
Response
  {
    "id"=> Data Set ID (integer),
    "name"=> Data Set Title (string),
    "hidden"=> Visibility (boolean),
    "url"=> Visualization URL (string),
    "path"=> Data Set Path (string),
    "createdAt"=>"January 28, 2014",
    "fieldCount"=> Number of fields (integer),
    "datapointCount"=> Number of data points (integer),
    "displayURL"=> Display URL (string)
  }
          
Notes
  • Setting recur=true as a get variable will return the associated Project(hash), Fields(hash), Data(hash)
POST Data Sets /api/v1/data_sets/append email(req), password(req), id(req)

Append new data to an existing data set with a username and password.

Response Codes
  • Success: 200 OK
  • Fail: 401:Unauthorized
  • Fail: 404 Not Found
  • Fail: 422 Unprocessable Entity
Data
  {
    "email" => "email address (string)",
    "password" => "password (string)",
    "id" => "data set id (integer)"
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }

  }
          
Example (Javascript)
    var apiUrl = 'https://isenseproject.org/api/v1/data_sets/append';

    var upload = {
        'email' : '(email)',
        'password' : '(password)',
        'id' : (data set id),
        'data' :  {
                    '(field id)' : [4,5,6] # new data to be added
                  }
    }

    $.post(apiUrl, upload);
          
Response
  {
    "id"=> Data Set ID (integer),
    "name"=> Data Set Title (string),
    "hidden"=> Visibility (boolean),
    "url"=> Visualization URL (string),
    "path"=> Data Set Path (string),
    "createdAt"=>"January 28, 2014",
    "fieldCount"=> Number of fields (integer),
    "datapointCount"=> Number of data points (integer),
    "displayURL"=> Display URL (string)
  }
          
Notes
  • A user can append to any data set that they have created or any data set that is on a project that he/she owns.
POST Data Sets /api/v1/data_sets/append contribution_key(req), id(req)

Append new data to an existing data set with a contribution key.

Response Codes
  • Success: 200 OK
  • Fail: 401:Unauthorized
  • Fail: 404 Not Found
  • Fail: 422 Unprocessable Entity
Data
  {
    "contribution_key" => "a contribution key (string)",
    "id" => "data set id (integer)"
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }

  }
          
Example (Javascript)
    var apiUrl = 'https://isenseproject.org/api/v1/data_sets/append';

    var upload = {
        'contribution_key' : '(key)',
        'id' : (data set id),
        'data' :  {
                    '(field id)' : [4,5,6] # new data to be added
                  }
    }

    $.post(apiUrl, upload);
          
Response
  {
    "id"=> Data Set ID (integer),
    "name"=> Data Set Title (string),
    "hidden"=> Visibility (boolean),
    "url"=> Visualization URL (string),
    "path"=> Data Set Path (string),
    "createdAt"=>"January 28, 2014",
    "fieldCount"=> Number of fields (integer),
    "datapointCount"=> Number of data points (integer),
    "displayURL"=> Display URL (string)
  }
          
Notes
  • You can only append data sets that were uploaded with the same key.

POST Media Objects /api/v1/media_objects email(req), password(req), upload(req), type(req), id(req)

Upload a media object to either a project or a data set. You can upload media objects to any project. You can upload media objects to any data set on a project that you own or any data sets that you have uploaded.

Response Codes
  • Success: 200 OK
  • Fail: 401 Unauthorized
  • Fail: 422 Unprocessable Entity
Data
  {
    "upload" => (file),
    "email" => "email address (string)",
    "password" => "password (string)",
    "type" => "(string) project or data_set",
    "id" => "ID of thing your pushing to (int)"

  }
          
Example (HTML) original code by Scott Cytacki
  <html>
    <head>
      <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
        <script type="text/javascript" src="example.js"></script>
    </head>
    <body>
      <input type="file" id="file-select"/>
      <button onclick="run();">Get</button>
    </body>
  </html>
          
Example (Javascript) original code by Scott Cytacki
// MEDIA OBJECT POST WITH USERNAME AND PASSWORD

    var apiUrl = 'https://isenseproject.org/api/v1/media_objects';
    var fileSelect = document.getElementById('file-select');
    var files = fileSelect.files;
    var formData = new FormData();
    var file = files[0];

    formData.append('upload', file, file.name);
    formData.append('email', '(email)');
    formData.append('password', '(password)');
    formData.append('type', '("data_set" or "project")');
    formData.append('id', (dataset id or project id));

    var xhr = new XMLHttpRequest();
    xhr.open('POST', apiUrl, true);
    xhr.send(formData);

          
Response
  {
    "id" => "ID of media object (int)",
    "mediaType" => "image",
    "name" => "name of file uploaded (string)",
    "url" => "URL of image (string)",
    "createdAt" => "February 06, 2014",
    "src" => "location of image",
    "tn_src"=>"location of thumbnail"
  }
          
Notes
  • type - "project" or "data_sets"
POST Media Objects /api/v1/media_objects contribution_key(req),contributor_name(req), upload(req), type(req), id(req)

Upload a media object to either a project or a data set. With a contribution key, you can upload a media object to the project or any data set that was uploaded with that key.

Response Codes
  • Success: 200 OK
  • Fail: 401 Unauthorized
  • Fail: 422 Unprocessable Entity
Data
  {
    "upload" => (file),
    "contribution_key" => "key created by project owner (string)",
    "contributor_name" => "Name of contributor (string)",
    "type" => "(string) project or data_set",
    "id" => "ID of thing your pushing to (int)"
  }
          
Example (HTML) original code by Scott Cytacki
  <html>
    <head>
      <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
        <script type="text/javascript" src="example.js"></script>
    </head>
    <body>
      <input type="file" id="file-select"/>
      <button onclick="run();">Get</button>
    </body>
  </html>
          
Example (Javascript) original code by Scott Cytacki
// MEDIA OBJECT POST WITH USERNAME AND PASSWORD

    var apiUrl = 'https://isenseproject.org/api/v1/media_objects';
    var fileSelect = document.getElementById('file-select');
    var files = fileSelect.files;
    var formData = new FormData();
    var file = files[0];

    formData.append('upload', file, file.name);
    formData.append('contribution_key', '(key)');
    formData.append('contributor_name', '(contributor's name)');
    formData.append('type', '("data_set" or "project")');
    formData.append('id', (data set id or project id));

    var xhr = new XMLHttpRequest();
    xhr.open('POST', apiUrl, true);
    xhr.send(formData);

          
Response
  {
    "id" => "ID of media object (int)",
    "mediaType" => "image",
    "name" => "name of file uploaded (string)",
    "url" => "URL of image (string)",
    "createdAt" => "February 06, 2014",
    "src" => "location of image",
    "tn_src"=>"location of thumbnail"
  }
          
Notes
  • type - either "project", or "data_set"

GET Users /api/v1/users/myInfo email(req),password(req)

Get your gravitar and full name.

Response Codes
  • Success: 200 OK
  • Fail: 401 Unauthorized
Example (Javascript)
    var urlProject = 'https://isenseproject.org/api/v1/users/myInfo';

    var responseProject = $.ajax({ type: "GET",
                                    url: urlProject,
                                  data : {'email' : '(email)',
                                       'password' : '(password)'},
                                  async: false,
                               dataType: "JSON"
    }).responseText;

    var parsedResponseProject = JSON.parse(responseProject);

    console.log(parsedResponseProject);
          
Response
    {
      gravatar: "gravatar url(string)"
      name: "display name (string)"
    }
          
Notes
  • N/A