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://app.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.