When importing data through the DMAPI, a XML descriptor file is used in conjunction with the file you want to import. This document will start by walking you through the types of data that can be import along with the structure of the XML descriptor file. Then we will dive into the creation of each of the sections of the XML descriptor file.

What type of data can be imported into SpatialKey?

  • CSV datasets
  • Shapefiles
  • Insurance datasets (these consist of two CSV files, one for the locations and another for the corresponding policies)

What does the XML descriptor file tell us?

Depending on which type of file you are importing, not all of the above options are required.

CSV Datasets Shapefiles Insurance Datasets
Dataset information * * *
Dataset permissions * * *
Notification options * * *
Column data types * *
Column data formats * *
Thematic mapping options * *
Geocoding options * *
Specific insurance dataset information *

There are various examples with each section in this document.  In addition to these, we have created sample datasets with accompanying complete XML descriptor files for Download to help get you started.

If you’d rather step through an XML file than read through this entire support article, here are a couple of examples to get you started:

[expand title=”Global Dataset Example”]

<?xml version="2.0" encoding="UTF-8"?>
<datasetImport>
    <permissions>      
<!---See Dataset Permissions for details and options--->
        <addAllUsers>false</addAllUsers>
        <denyExporting>true</denyExporting>
    </permissions>
    <notifications>      
<!---See Notification Options for details and options--->
        <sendEmail>true</sendEmail>
        <clientNotification>true</clientNotification>
    </notifications>
    <dataset>
        <latlon />      
<!---See Geocoding Options for details and options, 
if this were an example using actual geocoding, 
you would need to add the <geocode /> section here instead--->
        <thematicLayer>
            <thematicDataset>Cresta_2007</thematicDataset>
<!---See Thematic Mapping Options for details and options--->
        </thematicLayer>
        <thematicLayer>
            <thematicDataset>Countries</thematicDataset>
        </thematicLayer>
        <type>CSV</type>      
<!---See Dataset Information for details and options--->
        <name>API_test_4000</name>
        <preparedWith>Spatialkey API</preparedWith>
        <preparedDate>2013-12-04T13:34:25.583-05:00</preparedDate>
        <expirationDate>2013-12-14T13:34:25.579-05:00</expirationDate>
        <datasetColumn>      
<!---See Column Data Types and Formats for details and options--->
            <name>city</name>
            <label>city</label>
            <type>String</type>
        </datasetColumn>
        <datasetColumn>
            <name>st_zip</name>
            <label>st zip</label>
            <type>String</type>
        </datasetColumn>
        <datasetColumn>
            <name>county</name>
            <label>county</label>
            <type>String</type>
        </datasetColumn>
        <datasetColumn>
            <name>TIV</name>
            <label>TIV</label>
            <type>Currency</type>
            <format>USD</format>
        </datasetColumn>
        <datasetColumn>
            <name>lat</name>
            <label>lat</label>
            <type>Latitude</type>      
<!---This type is required because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>lon</name>
            <label>lon</label>
            <type>Longitude</type>      
<!---This type is required because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>st_geo_match</name>
            <label>st geo match</label>
            <type>String</type>
        </datasetColumn>
        <datasetColumn>
            <name>country</name>
            <type>CountryIso</type>      
<!---A Country Type is required when enabling global thematic layers,
if enabling US only thematic layers, country type isn't required,
see Thematic Mapping Options for details and options--->
            <thematicLayer>
<!---See Thematic Mapping Options for details and options--->
                <thematicDataset>Countries</thematicDataset>
            </thematicLayer>
        </datasetColumn>
        <datasetColumn>
            <name>cresta</name>
            <type>String</type>
            <thematicLayer>      
<!---See Thematic Mapping Options for details and options--->
                <thematicDataset>Cresta_2007</thematicDataset>
            </thematicLayer>
        </datasetColumn>
    </dataset> 
</datasetImport>

[/expand]

[expand title=”US Dataset Example”]

<?xml version="2.0" encoding="UTF-8"?>
<datasetImport>
    <permissions>      
<!---See Dataset Permissions for details and options--->
        <addAllUsers>false</addAllUsers>
        <denyExporting>true</denyExporting>
    </permissions>
    <notifications>      
<!---See Notification Options for details and options--->
        <sendEmail>true</sendEmail>
        <clientNotification>true</clientNotification>
    </notifications>
    <dataset>
        <geocode>
<!---See Geocoding Options for details and options, 
if this were an example using latitude/longitude coordinates, 
you would need to add the <latlon /> section here instead--->
            <geocoder>SpatialKey_Free</geocoder>
            <defaultState />
            <defaultCity />
            <defaultCounty />
            <defaultCountry />
            <defaultPostalCode />
            <defaultStreet />
        </geocode>
        <pointThematicLayer>
<!---See Thematic Mapping Options for details and options--->
            <thematicDataset>US_Postal</thematicDataset>
        </pointThematicLayer>
        <pointThematicLayer>
            <thematicDataset>US_Counties</thematicDataset>
        </pointThematicLayer>
        <pointThematicLayer>
            <thematicDataset>US_States</thematicDataset>
        </pointThematicLayer>
        <type>CSV</type>      
<!---See Dataset Information for details and options--->
        <name>API_test_4000</name>
        <preparedWith>Spatialkey API</preparedWith>
        <preparedDate>2013-12-04T13:34:25.583-05:00</preparedDate>
        <expirationDate>2013-12-14T13:34:25.579-05:00</expirationDate>
        <datasetColumn>      
<!---See Column Data Types and Formats for details and options--->
            <name>city</name>
            <label>city</label>
            <type>City</type>
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>street</name>
            <label>Street</label>
            <type>Street</type>
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>st_zip</name>
            <label>st zip</label>
            <type>PostalCode</type>
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>county</name>
            <label>county</label>
            <type>County</type>
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>TIV</name>
            <label>TIV</label>
            <type>Currency</type>
            <format>USD</format>
        </datasetColumn>
        <datasetColumn>
            <name>country</name>
            <label>Country</label>
            <type>CountryName</type>     
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
    </dataset> 
</datasetImport>

[/expand]

Dataset information

There is some basic information that must be included in each XML descriptor file:

Metadata Default Effect
type none Select either CSV or Shapefile. This will determine the type of import that is processed.
name none This name will appear in SpatialKey for the imported dataset.
description none This is only metadata, optional.
preparedWith none Enter something like “SpatialKey API” here. This is only metadata, optional.
preparedDate none This is metadata only, optional. Expected format is UTC.
expirationDate none This sets an expiration date for when the dataset gets deleted. If the dataset is used in a saved dashboard, it will not be deleted on the expiration date. Expected format is UTC.
expireIn none This sets an expiration date in minutes from the time data is uploaded. For example if it is set to 60 the dataset will expire one hour from the time the data is uploaded. If both expireIn and expirationDate are specified in the XML expireIn will override the expirationDate

Note that only type and name are required, the others are optional.

If expirationDate or expireIn are less than five days than the current time then the dataset will not count against the quota. This is typically used for temporary datasets (Underwriting accounts or schedules)

[expand title=”Example XML for Dataset Information”]

<dataset>
    <type>Shapefile</type>
    <name>110th Congressional District</name>
    <preparedWith>SpatialKey API</preparedWith>
    <preparedDate>2013-11-08T16:42:11.379-05:00</preparedDate>
    <expirationDate>2014-11-08T16:42:11.379-05:00</expirationDate>
</dataset>

[/expand]

Dataset permissions

The following permissions can be set:

Option Default Effect
addAllUsers false Allows all users in your organization to be able to view the uploaded dataset.
denyExporting false Prevents the created dataset from being exported back out of SpatialKey.
hideFromUI false Hides the dataset from the “Manage Data” page in the SpatialKey client.  The dataset is still accessible if directly linked and using its ID.  The dataset will still count towards your dataset quota.
viewers none Allows you to add specific users in your organization as viewers for this dataset.
managers none Allows you to add specific users in your organization as managers (collaborators) for this dataset.
owners none (creator is implicit) Allows you to add specific users in your organization as owners (editors) for this dataset.

Viewers, Managers (collaborators), and Owners (editors) can accept any number of users identified either by their email (they must already have an account) or their user ID (viewable from the ‘People’ page in SpatialKey). Viewers, Managers (collaborators), and Owners (editors) can also accept any number of groups, identified by the group ID or group Name (viewable from ‘People’ page in SpatialKey) .

[expand title=”Example XML for Dataset Permissions”]

<permissions>
    <addAllUsers>false</addAllUsers>
    <denyExporting>true</denyExporting>
    <hideFromUI>true</hideFromUI>
    <viewers>
        <email>go@uld.com</email>
        <email>kilroy@here.co.uk</email>
    </viewers>
    <managers>
        <id>8a808bb2409c712501409c7a6a330009</id>
        <group>8a808bb2409c712501409c7a6a367843</group>
        <groupName>The Beatles</groupName>
    </managers>
    <owners>
        <id>8a808bb23c9f212501409c7a6a912482</id>
        <email>john.smith@who.com</email>
    </owners>
</permissions>

[/expand]

Notification options

The following notifications are available:

Option Default Effect
sendEmail false Notify the authenticated user through email.
clientNotification false Notify the authenticated user through the SpatialKey client.

[expand title=”Example XML for Notification Options”]

<notifications>
    <sendEmail>true</sendEmail>
    <clientNotification>true</clientNotification>
</notifications>

[/expand]

Column data types and formats

Within the API, column data types and formats are defined for CSV datasets:

Option Default Effect
name none Column name that will appear in SpatialKey.
label none Label that will appear in SpatialKey.
type none Defines the data type for the column.
format none Defines the format for the column.

Generic Data types and formats used in XML

Note that data formats only specify how the data will display in SpatialKey and are completely optional. Some examples are provided below this table. Note that data types and formats are case sensitive.

Data Types Data Formats
String -none-
Decimal -none- (displays as a decimal)
Hours
Minutes
Seconds
Milliseconds
Boolean -none-
Integer -none-
ID
Currency -none- (default is USD)
USD
JPY
CNY
GBP
EUR
AUD
CAD
CHF
Date -none- (default is Year)
Second
Minute
Hour
Day
Month
Year
Percentage -none-

[expand title=”Data Formatting Examples”]
In this case the numeric data will be formatted as a string. It also prevents this column from being shown in areas where aggregate functions are exposed and treats it as a string column in the user interface. Note that 20000 would be displayed as 20000 in the example below (without a type of ID it would be shown as 20k).

<type>Integer</type>
<format>ID</format>

This example assumes that the numeric data is in hours and it will display the total time in days and hours as shown below. Note that 50000 would be displayed as 2,083d 8h in the hours example below and would be displayed as 13h 53m 20s in the seconds example below.

<type>Integer</type>
<format>Hours</format>
<type>Integer</type>
<format>Seconds</format>

This example shows how to format dates independent of the format that was imported into SpatialKey. When importing dates it is best to import data that displays down to the minute or second and use the “format” option to control display. Note that 2009-09-19 15:24:46 would be displayed as 09/19/2009 in the day example below and would be displayed as 2009 in the year example below.

<type>Date</type>
<format>Day</format>
<type>Date</type>
<format>Year</format>

[/expand]

Other data types used in XML

Thematic specific data types:

  • CountryIso
  • CountryFips

Geocoding specific data types:

  • Street
  • City
  • State
  • PostalCode
  • County
  • CountryName
  • Latitude
  • Longitude
  • Accuracy

[expand title=”Example XML for Data types and formats”]

<datasetColumn>
    <name>tiv</name>
    <label>TIV</label>
    <type>Currency</type>
    <format>USD</format>
</datasetColumn>
<datasetColumn>
    <name>a_number</name>
    <label>Example label</label> 
    <type>Double</type>
</datasetColumn>
<datasetColumn>
    <name>pct_lt100</name>
    <label>pct lt100</label>
    <type>Percentage</type>
</datasetColumn>
<datasetColumn>
    <name>expiration_date</name>
    <label>Expiration Date</label>
    <type>Date</type>
    <format>Day</format>
</datasetColumn>

[/expand]

Thematic mapping options

Thematic maps show a color-coded distribution of a metric for a given unit of geography, like states/provinces, postal codes, or custom business territories. They quickly help visualize key geographic contributors and highlight outliers and trends for datasets. Thematic mapping is just one way of visualizing your data on a map. For more details, click here.

SpatialKey supports two different types of thematic maps, point in poly and column match:

  • Point in poly uses the location (lat/lon or derived from gecode) and intersects it with the boundary data to determine which shape it will be represented by.
  • A column match matches your data with data from the boundary file. For example if you are using a column match and are mapping postal codes and you have 12345 as a postal code value in your data that will match to the postal code 12345 in the boundary data. SpatialKey will display a match % if there are values in your data that do not align with the boundary data.
Thematic Layers Point in Poly Column Match Notes
US_States *
US_Counties *
US_Postal *
Countries * Can use either ISO or FIPS Country Codes.
Cresta_2007 * This layer must be licensed by your organization to use.
Cresta_2010 * This layer must be licensed by your organization to use.
Cresta_LowResolution_2013 * This layer must be licensed by your organization to use.
PostalCode_HighResolution * This layer must be licensed by your organization to use.
PostalCode_LowResolution * This layer must be licensed by your organization to use.

Country Defintion

Some of the thematic layers above require country to be defined in the XML in order for them to be enabled. Only the US thematic layers don’t require a country to be defined because when a county isn’t defined, it’s assumed that the country for the data is US.

[expand title=”Example XML for Country Definition”]

Example defining a specific county code for the entire dataset:

<dataset>
    ...
    <isoCountry>GB</isoCountry>
    ...
</dataset>

Examples defining the country column:

<datasetColumn>
    <name>country</name>
    <type>CountryIso</type>
</datasetColumn>
<datasetColumn>
    <name>country</name>
    <type>CountryFips</type>
</datasetColumn>

[/expand]

US Only Thematic Layers

If your data is only in the US we support three levels of US thematic. You can choose to enable all layers or only the layers you need to display for your data.  The US thematic layers use the point location of your data and perform a point in poly join.

[expand title=”Example XML for US Thematic Options”]

A typical US Thematic layer linkage would look like the following:

<pointThematicLayer>
    <thematicDataset>US_Postal</thematicDataset>
</pointThematicLayer>
<pointThematicLayer>
    <thematicDataset>US_Counties</thematicDataset>
</pointThematicLayer>
<pointThematicLayer>
    <thematicDataset>US_States</thematicDataset>
</pointThematicLayer>

[/expand]

Global Thematic Layers

Before global thematic layers can be enabled, a country code or column in the dataset must be identified. Country columns are identified by either “CountryIso” or “CountryFips”. If a country code is defined rather than a column, it is expected to be in ISO format.

Note that if a Country isn’t specified, US is assumed.

[expand title=”Example XML for Global Thematic Options”]

To enable a global thematic layer, specify a thematicLayer in the column to indicate how you want to link it as well as adding it to your thematic layers for your dataset. Note: definition of  the thematic layer in the header of the dataset section in the XML file is optional, it’s only required that the thematic layer be defined for the specific dataset column.

<thematicLayer>
    <thematicDataset>Cresta_2007</thematicDataset>
</thematicLayer>
...
<datasetColumn>
    <name>cresta</name>
    <type>String</type>
    <thematicLayer>
        <thematicDataset>Cresta_2007</thematicDataset>     
    </thematicLayer> 
</datasetColumn>

[/expand]

Geocoding options

This section of the API is all about telling SpatialKey where to place your points on the map.  There are a couple of options for providing this information:

  • Dataset contains latitude and longitude coordinates
  • Dataset contains address information that needs to be geocoded (SpatialKey supports the use of a variety of geocoders, some which require additional licensing. For more details, click here.)
  • Previously geocoded locations can be skipped and SpatialKey will only attempt to geocode those with null or 0,0 lat/longs – referred to as hybrid geocoding in the Data Import API

Note: it’s possible that your dataset doesn’t contain information to place points on the map – providing this information is completely optional. 

Latitude and Longitude Coordinates

Column Type Required?
Latitude y
Longitude y
Accuracy n

Note that the Accuracy column defines the accuracy level of the latitude and longitude coordinate for the record in the dataset.  For details on valid accuracy levels, check out this article.

Street Addresses to be Geocoded

Column Type Required?
Street n
City n
PostalCode n
County n
State n
CountryName n

Note that only one of these columns are required to trigger geocoding, but the more that are identified will result in better geocoding results.  

Note that if you don’t have a column in your data representing State, but all records in the dataset are in the same state, you can enter the State code in the XML as the default state. This applies to other address fields like City, Country, etc. as well.  [expand title=”Example”]

E.g. Geocode with Address Information – State column doesn’t exist but all records are in NY.

<geocode>
    <geocoder>SpatialKey_Free</geocoder>
    <defaultState>NY</defaultState>
    <defaultCity />
    <defaultCounty />
    <defaultCountry />
    <defaultPostalCode />
    <defaultStreet />
</geocode>

[/expand]

Geocoders: If using ‘Street Addresses to be Geocoded’, a geocoder must be specified.

  • SpatialKey_Free
  • TomTom_Premium
  • Mapquest_Premium
  • Google_Premium
  • Note: If you license an additional geocoder, please contact us for the appropriate geocoder name to use with the API.

Hybrid geocoding (Skip Previously Geocoded Locations)

Column Type Required?
Latitude y
Longitude y
Street n
City n
PostalCode n
County n
State n
CountryName n

Specifying latitude and longitude columns along with any combination of the other address fields is required for hybrid geocoding. A geocoder must be specified for hybrid geocoding.

Note that geocoding accuracy cannot be specified for latitude/longitude coordinates in hybrid geocoding mode.

[expand title=”Example XML’s for Geocoding Options”]

Geocode with Address Information.  Assume you have columns for City and Street in your data, hardcode default State = NY.

<geocode>  
    <geocoder>SpatialKey_Free</geocoder>
    <!---Assumes all records are in NY.--->
    <defaultState>NY</defaultState>
    <defaultCity />
    <defaultCounty />
    <defaultCountry />
    <defaultPostalCode />
    <defaultStreet />
</geocode>
<datasetColumn>
    <name>street</name>
    <label>Street</label>
    <type>Street</type>
</datasetColumn>
<datasetColumn>
    <name>city</name>
    <label>City</label>
    <type>City</type>
</datasetColumn>
...

Use Latitude and Longitude Coordinates

<dataset>
    <latlon />
    ....
    <datasetColumn>
        <name>lat</name>
        <label>lat</label>
        <type>Latitude</type>
    </datasetColumn>
    <datasetColumn>
        <name>lon</name>
        <label>lon</label>
        <type>Longitude</type>
    </datasetColumn>
    ...
</dataset>

Hybrid geocoding. Specify geocoding details in the <hybrid> section and ensure you have identified latitude and longitude column types in your data.

<hybrid>  
    <geocoder>SpatialKey_Free</geocoder>
    <defaultState />
    <defaultCity />
    <defaultCounty />
    <defaultCountry />
    <defaultPostalCode />
    <defaultStreet />
</hybrid>
<datasetColumn>
    <name>street</name>
    <label>Street</label>
    <type>Street</type>
</datasetColumn>
<datasetColumn>
    <name>city</name>
    <label>City</label>
    <type>City</type>
</datasetColumn>
<datasetColumn>
    <name>lat</name>
    <label>lat</label>
    <type>Latitude</type>
</datasetColumn>
<datasetColumn>
    <name>lon</name>
    <label>lon</label>
    <type>Longitude</type>
</datasetColumn>
...

[/expand]

Specific insurance dataset information

In addition to basic datasets we also support Insurance datasets which combine a location and policy dataset together. With this configuration we also support policy exposed limits calculations within a dashboard if the appropriate fields are identified. Insurance datasets are able to be used in the Policy Exposed Limit feature in SpatialKey.

To learn more about the XML file requirements for insurance datasets, click here.

Download Sample Datasets and XML Descriptor Files

We have walked through each piece of the XML file with all possible options above, but how do all of these pieces come together in the final XML Descriptor File?

[expand title=”Full XML Example – Global Dataset”]

Note that this is the same example as provided in the beginning of this document.

<?xml version="2.0" encoding="UTF-8"?>
<datasetImport>
    <permissions>      
<!---See Dataset Permissions for details and options--->
        <addAllUsers>false</addAllUsers>
        <denyExporting>true</denyExporting>
    </permissions>
    <notifications>      
<!---See Notification Options for details and options--->
        <sendEmail>true</sendEmail>
        <clientNotification>true</clientNotification>
    </notifications>
    <dataset>
        <latlon />      
<!---See Geocoding Options for details and options, 
if this were an example using actual geocoding, 
you would need to add the <geocode /> section here--->
        <thematicLayer>
            <thematicDataset>Cresta_2007</thematicDataset>
<!---See Thematic Mapping Options for details and options--->
        </thematicLayer>
        <thematicLayer>
            <thematicDataset>Countries</thematicDataset>
        </thematicLayer>
        <type>CSV</type>      
<!---See Dataset Information for details and options--->
        <name>API_test_4000</name>
        <preparedWith>Spatialkey API</preparedWith>
        <preparedDate>2013-12-04T13:34:25.583-05:00</preparedDate>
        <expirationDate>2013-12-14T13:34:25.579-05:00</expirationDate>
        <datasetColumn>      
<!---See Column Data Types and Formats for details and options--->
            <name>city</name>
            <label>city</label>
            <type>String</type>
        </datasetColumn>
        <datasetColumn>
            <name>st_zip</name>
            <label>st zip</label>
            <type>String</type>
        </datasetColumn>
        <datasetColumn>
            <name>county</name>
            <label>county</label>
            <type>String</type>
        </datasetColumn>
        <datasetColumn>
            <name>TIV</name>
            <label>TIV</label>
            <type>Currency</type>
            <format>USD</format>
        </datasetColumn>
        <datasetColumn>
            <name>lat</name>
            <label>lat</label>
            <type>Latitude</type>      
<!---This type is required because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>lon</name>
            <label>lon</label>
            <type>Longitude</type>      
<!---This type is required because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>st_geo_match</name>
            <label>st geo match</label>
            <type>String</type>
        </datasetColumn>
        <datasetColumn>
            <name>country</name>
            <type>CountryIso</type>      
<!---A Country Type is required when enabling thematic layers,
if enabling US only thematic layers, country type isn't required,
see Thematic Mapping Options for details and options--->
            <thematicLayer>
<!---See Thematic Mapping Options for details and options--->
                <thematicDataset>Countries</thematicDataset>
            </thematicLayer>
        </datasetColumn>
        <datasetColumn>
            <name>cresta</name>
            <type>String</type>
            <thematicLayer>      
<!---See Thematic Mapping Options for details and options--->
                <thematicDataset>Cresta_2007</thematicDataset>
            </thematicLayer>
        </datasetColumn>
    </dataset> 
</datasetImport>

[/expand]

[expand title=”Full XML Example – US Dataset”]

<?xml version="2.0" encoding="UTF-8"?>
<datasetImport>
    <permissions>      
<!---See Dataset Permissions for details and options--->
        <addAllUsers>false</addAllUsers>
        <denyExporting>true</denyExporting>
    </permissions>
    <notifications>      
<!---See Notification Options for details and options--->
        <sendEmail>true</sendEmail>
        <clientNotification>true</clientNotification>
    </notifications>
    <dataset>
        <geocode>
<!---See Geocoding Options for details and options, 
if this were an example using latitude/longitude coordinates, 
you would need to add the <latlon /> section here instead--->
            <geocoder>SpatialKey_Free</geocoder>
            <defaultState />
            <defaultCity />
            <defaultCounty />
            <defaultCountry />
            <defaultPostalCode />
            <defaultStreet />
        </geocode>
        <pointThematicLayer>
            <thematicDataset>US_Postal</thematicDataset>
        </pointThematicLayer>
        <pointThematicLayer>
            <thematicDataset>US_Counties</thematicDataset>
        </pointThematicLayer>
        <pointThematicLayer>
            <thematicDataset>US_States</thematicDataset>
        </pointThematicLayer>
        <type>CSV</type>      
<!---See Dataset Information for details and options--->
        <name>API_test_4000</name>
        <preparedWith>Spatialkey API</preparedWith>
        <preparedDate>2013-12-04T13:34:25.583-05:00</preparedDate>
        <expirationDate>2013-12-14T13:34:25.579-05:00</expirationDate>
        <datasetColumn>      
<!---See Column Data Types and Formats for details and options--->
            <name>city</name>
            <label>city</label>
            <type>City</type>
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>street</name>
            <label>Street</label>
            <type>Street</type>
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>st_zip</name>
            <label>st zip</label>
            <type>PostalCode</type>
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>county</name>
            <label>county</label>
            <type>County</type>
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
        <datasetColumn>
            <name>TIV</name>
            <label>TIV</label>
            <type>Currency</type>
            <format>USD</format>
        </datasetColumn>
        <datasetColumn>
            <name>country</name>
            <label>Country</label>
            <type>CountryName</type>     
<!---This type is identified because of the selected geocode method,
see Geocoding Options for details and options--->
        </datasetColumn>
    </dataset> 
</datasetImport>

[/expand]

Check out these downloadable examples

All of the following XML examples can be used with the same dataset. (preview dataset) (download dataset and XML files)

  • Geocode with SpatalKey_Free geocoder. (view XML)
  • Import with Latitude and Longitude coordinates. (view XML)
  • Import with Latitude and Longitude coordinates. Enable High Resolution Postal Code global thematic layer. Hardcode a single Country. (view XML)
  • Import with Latitude and Longitude coordinates. Enable High Resolution Portfolio Code and Low Resolution Postal Code global thematic layers.  Specify a country column in the dataset. (view XML)
  • Import with Latitude and Longitude coordinates. Enable US State, County, and Postal Code thematic layers. (view XML)

Please contact us if you need help setting up a XML for a shapefile.