Formatting a Location 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.

Location data sources contain one or more records, called entities, where each record contains information about a single location. Each location is defined by a pair of latitude and longitude coordinates. This type of data is also called point data because each entity defines a single location, or point, on the surface of the Earth.

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

Note

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

File Schema

Your file must be either a Microsoft Office Access 2002 or Microsoft Office Access 2003 XML file with an embedded schema or a delimited-field flat file where the first row defines the schema. Valid delimiters are commas, tabs, or pipes ( | ). You must use a single delimiter consistently throughout the file.

The schema cannot exceed 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 characters in the six columns added by the geocoding process—MatchCode, MatchedMethod, MatchedAddress, InputModified, EditedLocationUTC, and EditedPropertyUTC—do not count toward this limit.) The columns must be of the types shown in the following table. If you are using Microsoft Access to create your data source, use the data types and field sizes shown in the second column. If no field size is listed, use the default size for the data type.

Data type	Microsoft Access data type (field size)	Description
keyword	Text or Memo	The schema can include up to 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 per entity is 2,000.
info	Text or Memo	The schema can include up to 25 fields of type info . The maximum number of characters in one info field or among all info fields per entity is 2,560.
string	Text or Memo	The schema can include up to 50 searchable string fields. The maximum number of characters per string field is 256 and the maximum among all string fields per entity is 2,560.
double	Number (size Double)	The schema can include up to 20 fields of type double . The Latitude and Longitude fields 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 include up to 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 include up to 200 fields of type boolean.

Notes

When using Microsoft Access to create a data source file with keyword and info fields, the text Keyword: or Info: must precede the field name.
Microsoft Access data types of AutoNumber are changed to Long if you download the data source.
Valid values for Yes/No fields are 0 (false) and 1 (true). If you upload a data source in flat-file format that contains empty or null boolean fields, MapPoint preserves those fields by assigning them the value N. To later create a downloadable file from that data source, specify Delimited text for the file format. If you specify Microsoft Access 2002 or Microsoft Access 2003, MapPoint creates the downloadable file, but any subsequent upload will fail because N is not a valid Boolean value in XML.

Column Requirements

Each column must have a unique name of no more than 50 characters. For delimited flat files, the name can be followed by the data type in parentheses (no spaces are allowed). Valid data types are long, double, boolean, string, info, and keyword. Column names must be XML-compliant; that is, they cannot contain spaces or reserved characters.

Three columns are required for location data sources: Latitude, Longitude, and EntityID. Your data source file must contain the Latitude and Longitude columns; however, these fields can be empty. If these fields contain entries for particular entities, the values are accepted as correct, and those entities are not geocoded as part of the upload process. 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. For an Microsoft Access XML file, the Microsoft Access data type must be Number and the Microsoft Access field size must be Double for each of these columns.

The EntityID column must contain an integer identifier for each entity that is unique for that geometry type in a particular environment. For an Microsoft Access XML file, the Microsoft Access data type must be Number or AutoNumber and the field size must be Integer or Long Integer. For a delimited flat file, the data type must be long (the range is –2147483648 to 2147483647)

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.

Note

Although the CountryRegion column is not required, if your data source does not have a CountryRegion column that contains values, the geocoder uses the MapPoint.World data source for geocoding, and cannot geocode addresses to the street level. Also, note that the entry in the CountryRegion column for addresses in Puerto Rico should be PR.

MapPoint adds six additional columns to each location data source as part of the uploading and geocoding process: MatchCode, MatchedMethod, Matched Address, EditedLocationUTC, EditedPropertyUTC, and InputModified

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

Important

After uploading data to MapPoint, you can use the FindServiceSoap.FindNearby method of the MapPoint API to retrieve address information from your data source as properties of an Address object. However, the character limits for the properties of the Address class differ from the character limits for field sizes. Address properties have the following limits: 16 characters for PostalCode, 44 for CountryRegion, 1,024 characters for AddressLine, and 49 characters for the other properties. If the records in your data source exceed these limits, the values are truncated in the FindResults object that is returned by the FindNearby method. The original values in your data source remain unchanged.

Share via

Formatting a Location Data Source

File Schema

Column Requirements

See Also

Concepts

Additional resources