Formatting a Polygon Data Source

Article
03/28/2012

IMPORTANT: MapPoint Web Service was retired on November 18, 2011. Please see https://msdn.microsoft.com/en-us/library/dd877180.aspx for a list of current Bing Maps APIs.

Polygon data sources contain one or more records, called entities, where each record contains information in the EntityGeometry field about a geometric region that is defined by at least three vertices. Each vertex is identified by a pair of latitude and longitude coordinates. MapPoint Web Service renders the polygon by drawing the implied edges that connect the first vertex to the second, the second to the third, and the last one to the first. (The implied edges cannot cross one another.) This shape defines the exterior ring of the polygon. If the polygon contains other polygons, the boundaries of those polygons are called interior rings. A polygon can have multiple interior rings, but MapPoint supports only one level of nesting. That is, interior rings cannot have other polygons inside them.

Optionally, you can use the Latitude and Longitude fields to associate a particular point with a polygon, and the address fields to associate address information with that point as you would with a location data source. For example, you can use the Latitude and Longitude fields to define the location of the field office responsible for a particular sales territory bounded by the polygon.

Use the guidelines in this topic to create polygon data source files that work with MapPoint.

Note

Numbers given below are in the U.S. format, where a comma separates thousands.

File Schema

Your file must be a valid XML file in Microsoft® Access 2002 or Access 2003 XML format with an embedded schema. In addition to the standard World Wide Web Consortium (W3C) namespace declaration, the file must include the Microsoft Access namespace declaration as shown here: <root xmlns:xsd='https://www.w3.org/2001/XMLSchema' xmlns:od='urn:schemas-microsoft-com:officedata'>. Also, the schema must include the tag <xsd:any namespace='##other' /> to indicate that polygon geometry is included in the file.

The schema can contain a maximum of 300 columns, including required columns and columns added by MapPoint. (The maximum number of characters per entity is 2,560, regardless of the number of columns.) The columns must be of the data types listed in the following table.

Data type	Microsoft Access data type (field size)	Access data type (field size)
keyword	Text or Memo	The schema can include a maximum of 10 fields of type keyword and up to 350 keywords per field. The maximum number of characters for a single keyword is 50, and the maximum number of characters in one keyword field or among all keyword fields for an entity is 2,000.
info	Text or Memo	The schema can include a maximum of 25 fields of type info. The fields that you use to define the exterior and interior rings of the polygon must be of this type. The maximum number of characters in one info field or among all info fields for each entity is 2,560.
string	Text or Memo	The schema can include a maximum of 50 searchable string fields. The maximum number of characters in one string field is 256 and the maximum number of characters among all string fields for an entity is 2,560.
double	Number (size Double)	The schema can include a maximum of 20 fields of type double. The required Latitude and Longitude fields and the NELat, NELong, SWLat, and SWLong fields that MapPoint adds for each polygon entity count toward this maximum. The maximum number of characters in one double field is 30.
long	Number or AutoNumber (size Integer or Long Integer)	The schema can contain a maximum of 20 fields of type long. The EntityID field counts toward this maximum. The maximum number of characters in one long field is 20.
boolean	Yes/No	The schema can contain a maximum of 200 fields of type boolean.

Column Requirements

Each column must have a unique name of no more than 50 characters. Column names must be XML-compliant; that is, they cannot contain spaces or reserved characters

Four columns are required for polygon data sources: EntityID, EntityGeometry, Latitude, and Longitude.

The EntityID column must contain an integer identifier for each entity that is unique for that geometry type in a particular environment. The data type must be Number or AutoNumber and the field size must be Integer or Long Integer.

EntityGeometry is an XML element that requires an ExteriorRing child element and can optionally contain InteriorRing child elements. EntityGeometry defines the contents of the element as polygon geometry and the data defining the polygon is then contained in the child elements ExteriorRing and InteriorRing .

ExteriorRing is a string field containing the latitude and longitude coordinates for at least three vertices, the minimum that are necessary to define a polygon. Latitudes and longitudes are separated by commas and latitude/longitude pairs are separated by semicolons. InteriorRing is a string field containing the latitude and longitude coordinates for vertices defining a polygon that is contained within the polygon defined by the ExteriorRing element. Although these fields must be of type string, they are not subject to the 256 character limit for other string fields. A polygon entity can have multiple interior polygons. A polygon entity can have a maximum of 500 vertices regardless of the number of interior polygons.

As with location data sources, Latitude and Longitude fields are also required. When you upload a polygon data source, MapPoint evaluates each polygon and creates a rectangle that encompasses the polygon, called a bounding rectangle. MapPoint adds four fields to your data source for the latitude and longitude coordinates of the northeastern and southwestern corners of the rectangle. Additionally, if the Latitude and Longitude fields are empty, MapPoint fills them with the latitude and longitude of the center point of the bounding rectangle. Because a polygon can have an irregular shape, the point may not be inside the polygon. If the Latitude and Longitude columns contain values however, those values are accepted as correct.

Values in the Latitude column must be floating point numbers representing decimal degrees that range from –90 to 90. Values in the Longitude column must be floating point numbers representing decimal degrees that range from –180 to 180. The field size must be Double for each of these columns.

If you omit the data type for a column, MapPoint uses long for the EntityID column, double for the Latitude and Longitude columns, and string for all other columns.

MapPoint adds four additional columns to each polygon data source as part of the upload process: NELat, NELong, SWLat, and SWLong. MapPoint uses the data in the fields containing the latitude and longitude coordinates for the vertices of a polygon to determine the bounding rectangle for the polygon. These fields represent the latitude and longitude coordinates for the northeastern and southwestern corners of that rectangle.

In addition to the names of required columns and the columns added to the data source, MapPoint reserves a number of column names. None of these columns are required, but if you use these column names, the columns must contain the type of data that MapPoint expects. Note that some of these columns have a maximum number of characters that is less than standard for columns of that type. The following table lists the reserved columns.

Name	Description
Name	The name of the entity.
DisplayName	The name of the entity as you want it displayed in your application.
FormattedAddress	The address of the entity formatted for display in your application.
AddressLine	The street number and, optionally, the street name that is associated with the entity. This field can contain a maximum 256 characters.
PrimaryCity	The city name that is associated with where the entity is located. This field can contain a maximum of 256 characters.
SecondaryCity	For country/regions that use a second city in addresses, the name of the secondary city that is associated with the entity. This field can contain a maximum of 256 characters.
SubDivision	The name of the state, province, or other subdivision that is associated with the entity. This field can contain a maximum of 256 characters.
PostalCode	The ZIP Code or postal code that is associated with the entity. This field can contain a maximum of 256 characters.

Share via

Formatting a Polygon Data Source

File Schema

Column Requirements

See Also

Concepts

Additional resources