Easy Insight Logo

Easy Insight Legacy XML API Documentation

Table of Contents

What is the Easy Insight Legacy XML API?

The Easy Insight Legacy XML API is an XML API for publishing data into Easy Insight. This API is outdated and we recommend using our newer JSON API, found here.

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 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.
  • /app/xml/defineCompositeDataSource -- creates or updates a composite data source containing joins between multiple other data sources you have already defined.
  • /app/xml/addRows -- adds new rows of data to a data source.
  • /app/xml/replaceRows -- replaces the current contents of a data source with a new set of rows.
  • /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 /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:


                <response>
                <code>200</code>
                <dataSourceKey>A Unique Key for the Data Source</dataSourceKey>
                </response>
            

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.


                <rows dataSourceName="Sample Order Database">
                <row>
                <Customer>Acme</Customer>
                <Amount>500</Amount>
                <OrderDate>2010-11-12T12:00:00</OrderDate>
                </row>
                </rows>
            

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


    <defineCompositeDataSource>
    <dataSourceName>Your Data Source Name</dataSourceName>
    <dataSources>
    <dataSource>Contained Data Source Name or API Key</dataSource>
    </dataSources>
    <connections>
    <connection>
    <sourceDataSource>Source Data Source Name or API Key</sourceDataSource>
    <targetDataSource>Target Data Source Name or API Key</targetDataSource>
    <sourceDataSourceField>Join Field on the Source Data Source</sourceDataSourceField>
    <targetDataSourceField>Join Field on the Target Data Source</targetDataSourceField>
    </connection>
    </connections>
    </defineCompositeDataSource>

addRows reference

XML POST to /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 /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 /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 /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>
    <code>200</code>
    <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 /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 /app/xml/commit :


    <commit>
    <transactionID>Given Transaction ID</transactionID>
    </commit>

Twitter Logo