MetaPulse API v3

MetaPulse provides a simple API for you to list, read, create, update and destroy graph values

Mikel Lindsaar avatar
Written by Mikel Lindsaar
Updated over a week ago

MetaPulse has a simple API that is available for your use, any feedback is welcome. 

This document represents version 3 of the API. You can find all versions listed in our help article:

You can use the API to programatically list, read, create, update and destroy data points against your graphs.  There are rate limits and API usage limits on the MetaPulse API that you can read more about in our help article:

Setup

To begin, you will need the email you use to sign into MetaPulse along with the API key from your MetaPulse User Profile page.  

If you will be doing a lot of API calls, it is best practice to create an API user in MetaPulse and give this user profile the permissions needed to access the necessary graphs.  
​ 
While you can use your own email and API key, a dedicated API user account is recommended.

Testing Authentication

The first test you should do is make sure you can authenticate with the server. MetaPulse uses header based authentication, so you need to set two headers in your request: API-EMAIL  and API-KEY . The email is your user email, the API key is from your profile page. 

You can check authentication is working by doing the following command using the curl system utility:

curl -i \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     https://envisage.io/api/v3/authentication

Which should give you a 200 OK with an empty body looking something like:

HTTP/2 200 
date: Mon, 07 Jan 2019 02:35:35 GMT
content-type: text/html
...

This 200 OK means you have successfully connected to the server.

Using the Data Point API

Note all following date formats are YYYY-MM-DD 

You can find the graph ID (token) on the graphs page under the info button.

List All Data Points

To list all data points for a single graph, you can do:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     -d '{"graph_id":"<GRAPH_TOKEN>"}' \
     https://envisage.io/api/v3/data_points

So for example, if your API_EMAIL  was user@example.com  and your API_KEY  was sdlexamplekfj  and you wanted the data points for a weekly graph with the week ending on Thursday which had the graph token gra2example3 then the full command would be:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: user@example.com" \
     -H "api-key: sdlexamplekfj" \
     -X GET \
     -d '{"graph_id":"gra2example3"}' \
     https://envisage.io/api/v3/data_points

Which would return a JSON array looking something like this:

[
  {
    "graphToken": "gra2example3",
    "majorEvent": false,
    "note": null,
    "periodEnd": "2018-11-9",
    "periodStart": "2018-11-15",
    "value": "2.0"
  },
  {
    "graphToken": "gra2example3",
    "majorEvent": false,
    "note": "We launched the product this week!",
    "periodEnd": "2018-11-16",
    "periodStart": "2018-11-22",
    "value": "4.0"
  },
  {
    "graphToken": "gra2example3",
    "majorEvent": false,
    "note": null,
    "periodEnd": "2018-11-23",
    "periodStart": "2018-11-29",
    "value": "5.0"
  },
  ...
]

Create a Data Point

To create a data point for the 28th of November, 2018 with the value of 12, you would run the following command:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X POST \
     -d '{"graph_id":"<GRAPH_TOKEN>", \
          "period":"2018-11-28", \
          "value":"12"}' \
     https://envisage.io/api/v3/data_points

This would give the sample output:

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": null,
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "12.0"

Create Multiple Data Points at Once 

You can set set multiple data points to equal multiple values at once. This will create the data point if it does not exist, or over-ride the value and not if it does. For example, to set  the 28th and 29th of November, 2018 to equal 14 and 15, you would run the following command::

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X POST \
     -d '{"data_points": [{"graph_id":"<GRAPH_TOKEN>", \
          "value":"14", \
          "period": "28-11-2018"}, \
          {"graph_id": "<GRAPH_TOKEN>", \
          "value":"15", \
          "period": "29-11-2018"}]}' \
     https://envisage.io/api/v3/data_points/set_multiple

This would give the sample output:

HTTP/2 200 
date: Mon, 07 Jan 2019 03:04:49 GMT
content-type: application/json
...

Show a Data Point

To show the data point for a specific date: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     https://envisage.io/api/v3/data_points/2018-11-28

Which would provide the response:

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": null,
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "12.0"

Update a Data Point

To change an existing data point for the 28th of November, 2018 to equal 15, you would run the following command: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X POST \
     -d '{"graph_id":"<GRAPH_TOKEN>", \
          "period":"2018-11-28", \
          "value":"12"}' \
     https://envisage.io/api/v3/v3/data_points/set

Which would give you in response:

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": null,
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "15.0"
}

Set a Data Point

To set a data point for the 28th of November, 2018 to equal 15, creating it if it does not exist or updating it if it does, you would run the following command: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X PATCH \
     -d '{"graph_id":"<GRAPH_TOKEN>", \
          "value":"15"}' \
     https://envisage.io/api/v3/data_points/2018-11-28/set

Which would give you in response:

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": null,
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "15.0"

Increment a Data Point

You can increment a data point for the 28th of November, 2018 by 1, creating it if it does not exist and setting it to the value of 1 or updating it by 1 if it does. Passing in a note value will append it to the existing note (if any) joined with a new line.

To do this, you would run the following command: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X PATCH \
     -d '{"graph_id":"<GRAPH_TOKEN>", \
          "value":"1",
          "note":"Second Note",
          "period":"2018-11-28"}' \
     https://envisage.io/api/v3/data_points/increment

Which would give you in response if the graph already had the value of 15 and note of "First Note":

{
  "graphToken": "<GRAPH_TOKEN>",
  "majorEvent": false,
  "note": "First Note\nSecond Note",
  "periodEnd": "2018-11-28",
  "periodStart": "2018-11-28",
  "value": "16.0"
}

Note, passing a negative value will decrement the data point by the amount given.

Delete a Data Point

To delete the data point at the 28th of November, 2018, you would run the following command:

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X DELETE \
     -d '{"graph_id":"<GRAPH_TOKEN>"}' \
     https://envisage.io/api/v3/data_points/2018-11-28

Which should return 200 OK with an empty response:

HTTP/2 200 
date: Mon, 07 Jan 2019 03:04:49 GMT
content-type: application/json
...

Using the Graph API

List all Graphs for a User 

To get a list of all graph tokens and the graph name for a given user email, you can run the following command: 

curl -i \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "api-email: <API_EMAIL>" \
     -H "api-key: <API_KEY>" \
     -X GET \
     https://envisage.io/api/v3/graphs/list?email=mikel@example.com

Which should return 200 OK with an array of tokens and graph names: 

[
 {"token":"grawrddq12o","name":"Total Clients"},  
 {"token":"gra8sd2qkez","name":"Gross Income"}
]

Debugging

Getting APIs to work can be a real pain sometimes, especially if you don't have direct access to send requests out.

A good tool to figure out if you are sending the API request correctly is beeceptor.com which is a free service to show you what your application is actually sending to MetaPulse.

To use it, just make a new end point in BeeCeptor (call it whatever you want, we'll use envisage-test in this example), and then click the "Turn off rules" button, then send something like:

curl -i -H "api-key: API_KEY" \
        -H "api-email: bob@example.com" \
     https://test-envisage.free.beeceptor.com/authentication

After sending this you'll get something back like:

HTTP/1.1 200 OK
Date: Tue, 05 Feb 2019 12:23:29 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Vary: Accept-Encoding


Hey ya! Great to see you here. Btw, nothing is configured for this request path. Create a rule and start building a mock API.

Which shows you BeeCeptor got your message.

Going to https://beeceptor.com/console/test-envisage will then show you a request, whcih you can click and then view the headers of and see something like:

Which looks good!
​ 

Questions / Comments

If you have any questions or comments, please contact us via support.

Did this answer your question?