Easy Insight Logo
Easy Insight Logo
Call 1-(720)-316-8174

Data Push API

The Easy Insight API provides developers with the ability to programatically create data sources and push data into those data sources.

Benefits
Using a system that Easy Insight doesn't connect to yet? Use the Easy Insight API to publish in data from that system and you can start building the same reports and dashboards against that data as you can against any of the default connection types.
How do I authenticate?
The API uses basic HTTP authentication. You can either use your Easy Insight username and password or API key and secret key (recommended for security).
How do I make requests?
The specifics will depend on your programming language, but as a general rule, you'll be making HTTP POSTs of XML to the URLs listed below. Make sure to set 'Content-Type' and 'Accept' headers to 'application/XML' to identify the request and response formats.
What API calls are available?

You can make the following requests:

  • https://www.easy-insight.com/app/xml/defineDataSource -- creates or updates a data source. If the data source already exists, returns a unique key you can use to pass data into the data source.
  • https://www.easy-insight.com/app/xml/defineCompositeDataSource -- creates or updates a composite data source containing joins between multiple other data sources you have already defined.
  • https://www.easy-insight.com/app/xml/addRows -- adds new rows of data to a data source.
  • https://www.easy-insight.com/app/xml/replaceRows -- replaces the current contents of a data source with a new set of rows.
  • https://www.easy-insight.com/app/xml/replaceRows -- updates certain rows within the data source based on the specified where clauses.
How about a simple example?

For this first example, we'll create a data source with three fields and publish a row of data into the data source. First, XML for creating the data source, which will be a POST to https://www.easy-insight.com/app/xml/defineDataSource.

<defineDataSource> <dataSourceName>Sample Order Database</dataSourceName> <fields> <field dataType="grouping"> <key>Customer</key> </field> <field dataType="measure"> <key>Amount</key> </field> <field dataType="date"> <key>OrderDate</key> </field> </fields> </defineDataSource>

This call returns:

200 A Unique Key for the Data Source

You can use the value returned from dataSourceKey as a unique identifier for publishing data into the data source. Next, we publish data source into the data source by making a POST to https://www.easy-insight.com/app/xml/addRows.

Acme 500 2010-11-12T12:00:00

The result of these calls will be a data source inside of Easy Insight with the fields of Customer, Amount, and OrderDate, containing one row of data.

Response codes reference
With every call, there is a code tag returned as part of the response XML. More information is typically available in the rest of the XML, but as a general reference: 200 -- everything's good, call worked 400 -- something was wrong with the request 401 -- bad credentials 500 -- server error
defineDataSource reference
XML POST to https://www.easy-insight.com/app/xml/defineDataSource -- creates or updates a data source. If the data source already exists, returns a unique key you can use to pass data into the data source. <defineDataSource> <dataSourceName>Your Data Source Name</dataSourceName> <fields> <field dataType="grouping"> <key>customer</key> <name>Customer</name> </field> <field dataType="measure"> <key>orderAmount</key> <name>Order Amount</name> </field> <field dataType="date"> <key>orderdate</key> <name>Order Date</name> </field> </fields> </defineDataSource> Valid dataType attributes are grouping, measure, date, tags, latitude, longitude, and postal.
defineCompositeDataSource reference
XML POST to https://www.easy-insight.com/app/xml/defineCompositeDataSource -- creates or updates a data source. If the data source already exists, returns a unique key you can use to pass data into the data source.
addRows reference
XML POST to https://www.easy-insight.com/app/xml/addRows -- adds new rows of data to a data source. <rows dataSourceName="Your Data Source Name"> <row> <customer>Acme</customer> <orderamount>500</orderamount> <orderdate>2010-11-12T12:00:00</orderdate> </row> </rows>
replaceRows reference
XML POST to https://www.easy-insight.com/app/xml/replaceRows -- replaces the current contents of a data source with a new set of rows. <rows dataSourceName="Your Data Source Name"> <row> <customer>Acme</customer> <orderamount>500</orderamount> <orderdate>2010-11-12T12:00:00</orderdate> </row> </rows>
updateRows reference
XML POST to https://www.easy-insight.com/app/xml/updateRows -- updates certain rows within the data source based on the specified where clauses. <update> <rows dataSourceName="Your Data Source Name"> <row> <customer>Acme</customer> <orderamount>500</orderamount> <orderdate>2010-11-12T12:00:00</orderdate> </row> </rows> <wheres> <where whereType="string"> <key>customer</key> <value>Acme</value> </where> </wheres> </update> <update> <rows dataSourceName="Your Data Source Name"> <row> <customer>Acme</customer> <orderamount>500</orderamount> <orderdate>2010-11-12T12:00:00</orderdate> </row> </rows> <wheres> <where whereType="day"> <key>orderdate</key> <year>2010</year> <day>275</day> </where> </wheres> </update>
What if I have a lot of data to add?
If you have a lot of data to add, it probably won't all fit into one XML request. It's best to split it up into multiple requests, using the transactional API. To begin a transactional commit, do an XML POST to https://www.easy-insight.com/app/xml/beginTransaction passing an operation: add - data is appended to the data source named. replace - data replaces the current data in the data source. <beginTransaction> <dataSourceName>Your Data Source Name</dataSourceName> <operation>add</operation> </beginTransaction> The call will return a transaction ID in the response, which you can then use to load data into the data source, as below. <response> 200 <transactionID>A Unique Key for the transaction</transactionID> </response> You can then use that transaction ID to load records just like addRows/replaceRows above, but XML POST to https://www.easy-insight.com/app/xml/loadRows : <rows transactionID="Given Transaction ID"> <row> <Customer>Acme</Customer> <Amount>500</Amount> <OrderDate>2010-11-12T12:00:00</OrderDate> </row> </rows> When you are finished, all of the data will be copied into the data source by committing the data with an XML POST to https://www.easy-insight.com/app/xml/commit : <commit> <transactionID>Given Transaction ID</transactionID> </commit>