What is a Shapefile?
The ESRI Shapefile or simply a shapefile is a popular geo-spatial vector data format for geographic information systems (GIS) software. It is developed and regulated by ESRI as a open specification for data interoperability among ESRI and other software products.

Step 1: Obtain Shape Files
Step 2: Editing Shape Files
Step 3: Connect .SHP files to GMaps Plugin
Step 4: Extracting Shape Labels From DBF File
Step 5: Define GMaps Plugin Shape File Keys
Troubleshooting

STEP 1:
Obtain ESRI Shapefiles
Shapefiles are made available with many popular GIS solutions. There is a lot of data made available on the web, most commonly from organizations like CDC, or local governments. In many cases, boundary files are freely available on the internet. If your organization currently uses a GIS solution like ESRI or MapInfo, you can consult with your GIS solution expert. If there are specific shapefiles that your organization requires for development, please contact support.

When obtaining your Shapefiles, you will typically get a minimum of 3 files:

• SHP- The SHP file contains the data required to plot data points that make up the shapes. The .SHP file is linked directly to GMaps Plugin, where it is rendered as a layer.
• DBF- dBASE table contains all of the meta data that describes each individual shape in the .SHP file. The DBF is extremely important because the SHP file does not contain any meta data required for labels in your map.
• SHX- Index file used to combine SHP and DBF file for GIS solutions. This file is required to maintain the integrity of the files when used with GIS solutions. GMaps Plugin does NOT utilize the SHX, but it is important to keep all 3 files together in case if you need to edit the shape data within a GIS solution.
  Learn more about Shapefiles from the ESRI Shapefile Specification

Shapefile Requirements for use with GMaps Plugin
View Troubleshooting Guide

• GMaps Plugin only supports the Polygon and Polyline shape types.
• Shapefile projection should be WGS 84
• Shapefile sizing should be less than 2MB for the best dashboard performance

Shapefile Resources (thanks to VDS Technologies for pulling these together)

World

Select and download free geographic (GIS) data for any country in the world.

USA/Canada

Map Layers Warehouse (USA)
Airports, cities and towns, states, county boundaries, railroads, roads, shaded relief of North America, time zone, water features from the National Atlas of the United States.

Cartographic Boundary Files (USA)
Cartographic Boundary Files, Shapefile, digital outline map files - U.S. Census Bureau.

National Transportation Atlas Data Shapefile Download Center (USA)

The California Spatial Data Library (USA)

GeoBase (Canada)
GeoBase provides free geospatial data in shapefile format.

Europe

Download street, railway, POI  maps in shapefile format (.shp.zip).

Asia

Download street, railway, POI  maps in shapefile format (.shp.zip).

STEP 2:
Editing Shapefiles
GMaps Plugin will display the contents of .SHP files but does not provide any utilities for editing or manipulating shape data. For this we recommend using a GIS tool like ESRI ArcGIS or free open source tools like Quantum GIS. Both of these solutions will enable you to merge, delete, simplify, or re-project shapes to work well with GMaps Plugin. LEARN HOW TO EDIT SHAPEFILES WITH QUANTUM GIS

1. Open GMaps Plugin Property Sheet
2. For any series, select the "Shape Data"
3. Select the configuration icon
4. Select Shapefile, and then click "OK"
5. Bind the "Single shape file URL" property to a URL where the SHP or TXT file are located.
   See troubleshooting guide for more details

Note: When binding a .SHP file path to your local PC:
Use the file:// syntax instead of \\. In addition, you will need to ensure that your local flash player security settings allow access to the drive for which your .SHP is loaded.

Note: When binding a .SHP file path to a web server:
Not all web servers will support .SHP as a file type. The .SHP extension can be modified to ".TXT" by simply modifying the file extension.

The web server will require a crossdomain.xml file for GMaps Plugin to successfully access and load the .SHP (or .TXT) file. A crossdomain.xml file should be placed into the ROOT directory of your web/application server.
Download sample crossdomain.xml policy file

6. Save your dashboard before previewing
7. Preview your dashboard to ensure the shapefile loads in the map.

STEP 4:
Extracting Shape Labels from DBF File
With a shapefile successfully rendered in GMaps Plugin, you will need to link labels to identify each shape. With all of the metadata contained in the DBF file, you will need to extract that information.

GMaps Plugin does not currently support a direct import of a DBF file though you can easily view its contents inside of MSFT Excel.

1. Open Excel
2. From inside of Excel, Click Open
3. Set the file type to "ALL Files"
4. Open the DBF file
5. Copy the column(s) of data that you will use as unique identifiers (DBF Keys). Many times the filed will be an "ID" or "Name" which will identify each shape within the shape file.
   
   CRITICAL NOTE- Do NOT change the sort order of the DBF file when importing to Xcelsius. If the sort order for the data is not desirable, you will adjust it in Step 5 inside of Xcelsius.
   
   
6. Paste the column(s) from Excel into Xcelsius which will identify the SHP keys.

STEP 5:
Define GMaps Plugin Shapefile Keys
Shape Data Keys
Shape data keys provides absolute control over what contents from a Shape File are displayed inside of GMaps Plugin. Using DBF Key and Shape Data Key properties, dashboard designers can show/hide any shapes from a shapefile while using any sort order from business intelligence dashboard queries.

For example, if the contents of a DBF file are listed as: "AZ, CA, NM, KY" and the dashboard query returns data listed as "CA, NM, AZ". this scenario presents two challenges:

1. The sort order from the DBF is different from the actual dashboard data
2. Not all regions from the SHP / DBF are required for the required map analysis.

The DBF Key and Shape Data Keys are not required properties. However, if these properties are NOT defined, GMaps Plugin will display all shapes from the shape file and require you to use the data order from the DBF file.

Shape File Order Keys- The Shape File Order Keys are obtained directly from the DBF file and contain a distinct range of values obtained directly from the DBF file. The DBF file contains the labels/ids for each shape within a shape file and can be opened. (learn how to extract DBF data). Upon extracting the DBF data from the shapefile and binding it to the DBF key property, you can change the values but NOT the sort order. If you need to change the data order, you will do so when binding the Shape Data Keys.

Data Order Keys- The Shape Data Key property will contain a distinct range of values used to match the DBF Keys. During dashboard runtime, GMaps Plugin will evaluate the Shape Data Key and search for a matching DBF key. When the Shape Data Key matches the DBF Key, the corresponding shapes will display in GMaps Plugin. Otherwise the shapes are NOT displayed. The Shape Data Keys will define the data order for other GMaps Plugin properties including:

1. Select the configuration icon from the GMaps Plugin property sheet
2. Click on "Shape File URL"
3. Bind the DBF Key to a data range obtained from the DBF file.
   Note: The actual values within the DBF key can be changed to meet the requirements of your data source so you can modify the DBF key to match what your dashboard queries return. For example, if the DBF file value is "District of Columbia," you can modify the value to "DC" without impacting the dashboard.
4. Bind the Shape Data Key to a data range where you will control what shapes are visible from the .SHP file.

Troubleshooting

You have downloaded a shapefile connected the URL publish and no shapefile shows up. The following will walk you through a checklist to ensure you have everything configured correctly.

1. The shapefile appears in Xcelsius preview mode and on my desktop, but not when I deploy the dashboard to my web site/portal?
Yes- If it DOES work on your local PC but NOT when you published the SWF to your server, there are 3 common issues that cause the shapefile not to work

• The shapefile has been placed on a MS IIS web server and .SHP is not supported out of the box. Click here to learn how to enable SHP MIME support
• The web server where the SHP files are located needs a crossdomain.xml policy file
• You have deployed the SWF to a web server but the SHP files are still on your local PC or file share- This is not supported by flash player. When a SWF is accessed via HTTP, the SHP files must also be loaded via HTTP.

No- If it does not work at all, you should proceed to the next troubleshooting questions.

2. Does the shapefile does not appear at all

Quick checks:

1. Make sure the URL to your shapefile is bound to 1 cell
2. Make sure the URL to the shapefile is correct
3. In the shape data options, make sure that shapefile is selected and not CSV or Spreadsheet

Shapefile projection

If you did NOT obtain your shape data from Centigon Solutions, there is a chance that your shapefile is not configured properly for use in Google Maps. Different GIS data sets are captured for different purposes and saved with a specific projection. In many cases shapefiles obtained for use with GMaps Plugin simply have the wrong projection applied. The good news is that its extremely easy to change this using any GIS software. Our favorite is an open source tool called Quantum GIS. Instructions for downloading and re-projecting your shapefiles with Quantum GIS are available here: Editing Shapefiles

If you require help with this, our knowledgeable support staff is always here to help you: support@centigonsolutions.com

Shapefile Size

If your shapefile is large in size (1.5 MB) there is a chance that GMaps Plugin is simply lagging trying to consume and render all of the data points that make up your shapefile. If this is a scenario you are running into, there are several ways to simplify your shapefile. You can learn how to simplify your shapefiles in our editing shapefiles tutorial or contact support

Related Articles

Editing Shapefiles

Filtering and Drilling geo-data