API V1 Documentation

Get properties of a project.

• Success: 200 OK
• Fail: 404 Not Found

    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);
          

    {
      "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)
    }
          

• If recur is set to true, the function will also return 'dataSets', 'mediaObjects', and 'owner' objects

Get an array of all the projects.

• Success: 200 OK

    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);
          

    {
      "Projects"=> (array)
    }
          

• 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.

Create a new project.

• Success: 200 OK
• Fail: 401 Unauthorized
• Fail: 422 Unprocessable Entity

  {
    "email" => "email address (string)",
    "password" => "password (string)",
    "project_name" => (string)
  }
          

    var apiUrl = 'https://isenseproject.org/api/v1/projects';

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

    $.post(apiUrl, upload);
          

  {
    "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)
  }
          

• If a name is not given, one will be generated based on the user's name.

Create a new key for an existing project.

• Success: 201 Created
• Fail: 401 Unauthorized
• Fail: 409 Conflict
• Fail: 422 Unprocessable Entity

    {
        "email" => "email address (string)",
        "password" => "password (string)",
        "contrib_key" => {  'name' => "Key's Name(string)",
                            'key' => "Key (string)"
                         }
    }
          

    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);
          

    {
        "msg" => "Success or error message. (String)"
    }
          

• The user must be the owner of the project.

• Success: 302 Found

• Fail: 404 Not Found

  {
    "contribution_key" => "contribution key (string)"
  }
          

    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);
          

  {
    "contribution_key": "(string)"
  }
          

• N/A

Add a new field to a project.

• Success: 200 OK
• Fail: 401 Unauthorized
• Fail: 422 Unprocessable Entity

  {
    "email" => "email address (string)",
    "password" => "password (string)",
    "field" =>  {
                  "project_id" =>  integer,
                  "field_type" =>  integer,
                  "name" => string,
                  "unit" => string,
                  "restrictions" => string
                }
  }

          

    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);
          

  {
    "id"=> Field ID (integer),
    "name"=> Field name (string),
    "type"=> Field type (integer),
    "unit"=> Field units (string),
    "restrictions"=> Accepted Values(string)
  }

          

• 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 properties of a field.

• Success: 200 OK
• Fail: 404 Not Found

    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);
          

  {
    "id"=> Field ID (integer),
    "name"=> Field name (string),
    "type"=> Field type (integer),
    "unit"=> Field units (string),
    "restrictions"=> Accepted Values(string)
  }
          

• The user must be the owner of the project.

Get properties of a data set.

• Success: 200 OK
• Fail: 404 Unprocessable Entity

  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);
          

   {
    "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"]
      }
    }
          

• N/A

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

• Success: 200 OK
• Fail: 401 Unauthorized
• Fail: 422 Unprocessable Entity

  {
    "email" => "email address (string)",
    "password" => "password (string)",
    "title" => (string),
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }

  }
          

    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);
          

  {
    "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)
  }
          

• 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.

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

• Success: 200 OK
• Fail: 401 Unauthorized
• Fail: 422 Unprocessable Entity

  {
    "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"]
      }

  }
          

    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);
          

  {
    "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)
  }
          

• 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.

Edit an existing data set with a username and password.

• Success: 200 OK
• Fail: 401:Unauthorized
• Fail: 404 Not Found
• Fail: 422 Unprocessable Entity

  {
    "email" => "email address (string)",
    "password" => "password (string)",
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }

  }
          

    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);
          

  {
    "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)
  }
          

• 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)

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

• Success: 200 OK
• Fail: 401:Unauthorized
• Fail: 404 Not Found
• Fail: 422 Unprocessable Entity

  {
    "contribution_key" => "a contribution key (string)",
    "data" =>
      {
        "FIELD_ID" => [1,2,3,4,5],
        "FIELD_ID_2" => ["blue","red",,,"green"]
      }

  }
          

    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);
          

  {
    "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)
  }
          

• Setting recur=true as a get variable will return the associated Project(hash), Fields(hash), Data(hash)

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

• Success: 200 OK
• Fail: 401:Unauthorized
• Fail: 404 Not Found
• Fail: 422 Unprocessable Entity

  {
    "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"]
      }

  }
          

    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);
          

  {
    "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)
  }
          

• 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.

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

• Success: 200 OK
• Fail: 401:Unauthorized
• Fail: 404 Not Found
• Fail: 422 Unprocessable Entity

  {
    "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"]
      }

  }
          

    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);
          

  {
    "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)
  }
          

• You can only append data sets that were uploaded with the same key.

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.

• Success: 200 OK
• Fail: 401 Unauthorized
• Fail: 422 Unprocessable Entity

  {
    "upload" => (file),
    "email" => "email address (string)",
    "password" => "password (string)",
    "type" => "(string) project or data_set",
    "id" => "ID of thing your pushing to (int)"

  }
          

  <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>
          

// 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);

          

  {
    "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"
  }
          

• type - "project" or "data_sets"

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.

• Success: 200 OK
• Fail: 401 Unauthorized
• Fail: 422 Unprocessable Entity

  {
    "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)"
  }
          

  <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>
          

// 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);

          

  {
    "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"
  }
          

• type - either "project", or "data_set"

Get your gravitar and full name.

• Success: 200 OK
• Fail: 401 Unauthorized

    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);
          

    {
      gravatar: "gravatar url(string)"
      name: "display name (string)"
    }
          

• N/A