Share via

Formatting MapPoint Web Service Data Source Files

  • Article

Formatting MapPoint Web Service Data Source Files

As a MapPoint Web Service customer, you can have multiple custom data source files. Each data source can store one or more location records, called entities. By using multiple custom data sources, you can use different data sources for different types (also known as entity types) of data (gas stations versus convenience stores, for example), different chains within a parent company (two different hotel brands, for example), or even different purposes within your application. Your data source files must adhere to the limitations described in the following table.

Limitation

Comments

You can have up to 25 data sources.

The number of data sources you can have may be smaller depending on the size of each source.

Each data source must have at least one entity.

You cannot upload an empty file.

Each data source and the entities it contains must have a unique entity type.

The entity type is a user-defined alphanumeric string.

Each entity must have a unique integer ID.

That entity ID must be unique within a world, which is defined as a data source of a specific entity type within a specific environment.

Every entity has three required properties (EntityID, Latitude, and Longitude) and six properties added by the geocoder (MatchCode, MatchedAddress, MatchedMethod, EditedLocationUTC, EditedPropertyUTC, and InputModified). Therefore, every entity must have at least nine properties.

These properties must be named exactly as shown here. In most cases, you will also want to include address properties (AddressLine, CountryRegion, PrimaryCity, SecondaryCity, Subdivision, and PostalCode). In the data you submit for geocoding, the maximum size for the AddressLine, CountryRegion, PrimaryCity, SecondaryCity, Subdivision, and PostalCodefields is 256 characters. If you upload this geocoded data to MapPoint Web Service, you can use the FindServiceSoap.FindNearby method in the MapPoint Web Service API to return address information from your data source as properties of an Address object. However, the character limits for Address class properties differ from the limitations used for geocoding records: 16 characters for PostalCode, 1054 for AddressLine, and 49 for the other properties. If the records in your data source exceed these Address class limits, the values are truncated in the returned FindResults object. The original field values in your data source in MapPoint Web Service are unchanged. For any other fields, column headings must be XML compliant; that is, they must not contain spaces or reserved characters. They must be unique and no longer than 50 characters.

The Latitude and Longitude columns may be empty.

If these columns have values, these values will be used and the entity will not be geocoded as part of the upload process. Values in the Latitude column must be floating point numbers representing decimal degrees in the range -90 to 90. Values in the Longitude column must be floating point numbers representing decimal degrees in the range -180 to 180.

To get the best geocoding results, your data source must have a column for country/region with valid values for the country of each entity.

Without a valid value for country/region (and assuming the Latitude and Longitude columns are empty), the batch geocoder will geocode against the World data source (MapPoint.World). Because this data source does not have street-level data, the results will generally not be desirable.

A data source must not contain more than 15 million searchable non-Boolean cells.

This limit includes cells in the columns that may be added to the data source file by MapPoint during the uploading and geocoding process (MatchCode, MatchedMethod, MatchedAddress, EditedLocationUTC, EditedPropertyUTC, and InputModified). It does not include cells with the types info or keyword.

The combined size of all your data sources cannot be more than 2 gigabytes after being uploaded and uncompressed.

 

Any single file for uploading (either through the Customer Services site (https://mappoint-css.live.com/CSCV3/) or the API) cannot be more than 100 megabytes (compression is allowed).

Please note that the larger the file, the longer the upload will take.

Your file must be in either Microsoft Access 2002 or 2003 XML file format with an embedded schema or in delimited flat file format.

Delimiters for flat files are tabs, commas, or pipes ( | ).

If you use a flat file format, the first row defines the format that all subsequent rows must follow. Each column must have a name, and, if you want, the name can be followed by the data type in parentheses (no spaces are allowed). The allowed data types are Long, Double, Boolean, String, Info, and Keyword.

If you omit the data type, the default type for entity ID is Long (the range is -2147483648 to 2147483647), the default for Latitude and Longitude is Double, and the default for all others is String. Acceptable delimiters are commas, tabs, or pipes ( | ), and the delimiter used must be consistent throughout the file.

Illegal characters in data files.

The following characters are not allowed as part of your data in the data files. If any of these characters are present in a record, that record will simply be skipped.

<

>

;

All control characters (0x0000 - 0x001f and 0x007f - 0x009f)

If you try to upload an empty string, it will be stored as a null. Any white spaces in strings are preserved when uploaded.

If the Access data file format is used, the Access Data Type must be Number and the Access Field Size must be Double for the Latitude and Longitude columns. For entity ID, the Access Data Type must be Number and the Field Size must be Integer.

The schema must be embedded in the file.