Introduction

Welcome to the MapInfo Envinsa Location Platform Web Services. This guide provides descriptions and
examples for the developer who is writing applications that access the Location Utility Service.
In this section:

What is the Location Utility Service?

Location Utility Functionality

Reverse Geocoding Functionality

Gazetteer Functionality

Location Utility Functionality

The Location Utility Service has three major divisions of functionality: Geocoding, Reverse Geocoding, and
Gazetteer.

Geocoding Functionality
Geocoding turns ordinary data records containing address information into geographic objects that display on a
map by finding the geographic coordinates of the address. This helps visualize data relationships. For example,
once address records are geocoded, they can be used by the Route Service to display them as driving directions
between two addresses (locations). Once data has geographic references, spatial searches can be performed to
answer questions such as "Find all customers within 10 miles of this location." All geocode requests can:

Geocode an incomplete address and return a complete set of address information (a

normalized address).

Indicate the number of exact or close matches in the response for a particular address supplied
in the geocoding request.

Process one or more addresses in a single geocoding request.

Provide information on the quality of the result by using a match code.

The following sections highlight potential ways to apply this capability:

Determining Service Capabilities - The Location Utility Service is able to describe its
capabilities. It indicates what feature types it can service and what operations are supported on
each feature type. The service can return what feature types (contents) are available based on
the feature type alias.

Geocoding a Street Address - Geocode address information in order to display it on a map or to

perform spatial searches and queries. This is useful for displaying store locations and the
customers who are part of a store loyalty program on a map to determine market regions.

Geocoding a Street Intersection - Geocode a street intersection in order to display it on a map.

For example, a mobile subscriber could enter the nearest street intersection to view a map of
their location on the mobile device.

Geocoding a Postal Code Centroid - Postal code centroids represent the centre of a postal
code region. Being able to locate these centroids on a map lets you perform demographic
analysis to find market regions to target for advertising or direct mail.

Geocoding a Point of Interest from a Place Code - Geocode a point of interest in order to
display it on a map or perform searches and queries. For example, locate a specific restaurant
and then find all of the nearest automated banking machines (ATM). The result would be
displayed on a subscriber's mobile device.

Reverse Geocoding Functionality

Reverse-Geocoding is one of the basic capabilities provided by the Location Utility Service. This service returns a
postal code, city, city subdivision, MSA (Metropolitan Statistical Area), region type (urban, suburban, rural), street
intersections, and street addresses associated with a given geographic location (position or geometry). Multiple
locations can be submitted in a single request document. The following operations are supported by the Reverse
Geocoder Service:

Given a Position, the service is able to return one or more locations, such as addresses with
associated Point geometries, and optionally, the address ranges of these locations from the
given position as it is defined in the Position ADT (Abstract Data Type - a point location in a
well-known coordinate system).

The form of the returned addresses is based upon the preference as stated in the request. You
can specify a preference of street address, street intersection, or PositionOfInterest (Postal
Code, City, and State name). If not specified, the service defaults to street address.

The service is capable of returning all location information of a preferred type within an area
(Circle, Ellipse, Polygon, and Point).

The service is able to indicate the number of matches in the response (including zero) for a
given request. The service also can limit the number of responses returned. For example, you
can set the service to return only the 5 closest matches.

The following sections highlight potential ways to apply this capability:

Finding the Street Address from a Position - Determine an address of a given longitude/latitude
for both real-time, such as call center, situation and for an after-the-fact situation, such as
comparing the surroundings of a location to determine if an individual was near an off-limits
area.

Getting a PositionOfInterest from a Position - Provide a mobile subscriber with a list of the
nearest postal code, city, and state, given their current location.

Multi-Language Support - Provide reverse geocoding results in multiple languages for those
countries that have more than one official language.

Gazetteer Functionality
As part of the Location Utility Service, the Gazetteer service performs a world, country, or city geocode operation
that can find the position of a partial address containing only the city, state, or a place name, such as a landmark
or airport. The following operations are supported by the Gazetteer Service:

Search, based on country, country subdivision, city, city subdivision, landmark, or airport to
return the position.

The pattern search capability supports a wildcard character (*) as a search value in one or more
fields to return all available values for that particular field.

The following sections highlight potential ways to apply this capability:

Specifying Types of Gazetteer Searches - Specify the type of search to perform, such as
searching all cities, towns, and airports within a specific country, to return a list of match results
to choose from.

Performing a Gazetteer Request - Search a database of places around the world in order to
quickly display a map centered on a specific place in a country such as Lake Como, Italy.

2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com

Location Utility Geocode Capabilities

Once a Geocoder Service determines a position from a partial or complete address, then the pertaining
information becomes a location-based resource. This resource is easily used by another service, such as the
Directory or the Route Service.
This section describes how to develop and use the geocode capabilities of the Location Utility Service.
Note: All code samples can be tried using the EnvinsaDemo application included in the default Envinsa
installation.
In this section:

Determining Service Capabilities

Geocoding a Street Address

Geocoding a Street Intersection

Geocoding a Postal Code Centroid

Geocoding a Point of Interest from a Place Code

Parsed versus Unparsed Street Addresses

Determining Service Capabilities

The Location Utility Service is made up of three sub-services, Geocode, ReverseGeocode, and Gazetteer. Each
of these sub services have different sets of preferences or support different geographic areas and types of
capabilities. The Location Utility Service is unique, as the geocoding engines behind the service are different
depending on the locality or deployment. Therefore their capabilities may be different. Before sending a request to
the Location Utility Service, determine what capabilities are available by sending it a GetCapabilities request.

Inputs and Behaviors

Because of the varied capabilities the service can return, the GetCapabilities request must be customized to the
particular information desired. The GetCapabilities request can be focused on the capability type (geocode or
reverse geocode), the type of geocode/reverse geocode, or a specific country.
A GetCapabilities request can take the following inputs:

Input

Require
d

Description

Capability
Type

No

Specify Geocode or Reverse Geocode. This returns the list of supported countries,
supported levels of geocoding, and the preferences for the Location Utility Service.

Geocode
Type

No

The following level types can be supported:

StreetAddress
IntersectionAddress
PositionOfInterest
PostalCode
AdministrativeRegions - Geocoding and reverse geocoding based on the administrative
areas. These can contain different content levels: country subdivision, country secondary
subdivision, municipality, and municipality subdivision.
Custom - This is available for reverse geocoding only. It returns the content of any
custom layer where the given position is located.
In response to this request, the service returns all of the available countries that support
these geocode types.

Country

No

By specifying an ISO2 or ISO3 country code (for example, CA or USA), the service
returns a response that includes whether the specified country is supported and all the
capabilities specific to that country.

Custom
Content

No

This value is used for GetCapabilities requests specific to Reverse Geocode. This value
of Custom Content is sent so that the reverse geocode queries some other content

rather than the predefined content (StreetAddress, InteresctionAddress, or

PositionOfInterest). Some examples of alternate queries include City and State. The
custom content must be defined in the Location Utility Service configuration
(see Reverse Geocode Preferencesfor more information).

Outputs
Depending on the type of GetCapabilities request that is sent, the service returns an appropriate response. Each
response includes the general preferences and their default values, all the geocode types available for the
specified country, as well as the geocode engine version, data version, license information, any additional fields
defined, local geocode preferences, any address and user dictionaries defined, and the order that these
dictionaries are searched.

Capability Type Response

In response to a successful GetCapabilities capability type request, the service returns a response that includes
the different levels of geocoding or reverse geocoding that are available and which countries support that level, as
well as all the other general information detailed previously.

Geocode Type Response

In response to a successful GetCapabilities capability type request, the service returns a response that includes
the information for the geocode type specified in the request. as well as all the other information detailed
previously.

Country Specific Response

In response to a successful GetCapabilities country request, the service returns a response that includes all the
geocode types available for the specified country, as well as all the other information detailed previously.

Java Code Sample

The following example returns whether the geocode capabilities for the US and Canadian services
(setCountry(new String[]{"US", "CAN"})) support Street Address geocoding (setLevelType("IntersectionAddress")),
and return all of the capabilities, including preferences for the Canadian service (setCountry(new String[]{"CA"})).

LocationCapability[] geocode = new LocationCapability[2];

geocode[0] = new LocationCapability();
// query the street address level geocode capabilities.
geocode[0].setLevelType(LocationCapability.TYPE_STREET_ADDRESS);
geocode[0].setCountry(new String[] { "US", "CAN" });
geocode[1] = new LocationCapability();
// query the street interseciton level geocode capabilities.
geocode[1].setLevelType(LocationCapability.TYPE_INTERSECTION_ADDRESS);
geocode[1].setCountry(new String[] { "CA" });
request.setGeocodeCapabilities(geocode);

.NET Code Sample

The following example returns all of the preferences for the Canadian service (ctr = {"CAN"}). The levels of
geocoding are not returned for this request (hasGeocodeLevelType = false).

private static GetCapabilityRequest getCapabilityRequest()

{
GetCapabilityRequest gC = new GetCapabilityRequest();

GeocodeCapability [] gcap = new GeocodeCapability[2];

gcap[0] = new GeocodeCapability();
string [] ctr = {"CAN"};
gcap[0].CountryISO = ctr;
gC.GeocodeCapability = gcap;
GeocodeCapability [] gcap1 = new GeocodeCapability[1];
gcap1[0] = new GeocodeCapability();
string [] ctr1 = {"USA"};
gcap1[0].CountryISO = ctr1;
gC.ReverseGeocodeCapability = gcap1;
return gC;
}

XML Sample
The following example returns all of the geocode capabilities and preferences for the Canadian service and all of
the Reverse Geocode capabilities for the US service.

<_RequestParameters xsi:type="ns3:GetCapabilitiesRequestType"
xmlns:ns3="http://www.mapinfo.com/locationutility">
<ns3:Geocode>
<ns3:Country>CAN</ns3:Country>
</ns3:Geocode>
<ns3:ReverseGeocode>
<ns3:Country>USA</ns3:Country>
</ns3:ReverseGeocode>
</_RequestParameters>

2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com

Geocoding a Street Address

The Location Utility Service can geocode various forms of a Street Address. These addresses could be made up
of different address types, address elements, levels of accuracy, or preferences.

Address Types
There are two main types of addresses that can be geocoded by the Location Utility Service.

Free Form Address (Unformatted)

The Free Form Address has all the address segments as well as the country and postal code in one string. The
Location Utility requires that the Free Form Address follows certain rules. The format of the address is read by the
service as: Street Address, Municipality, CountrySubdivision; PostalCode.
A comma is the separator between the different address segments. A semicolon is the separator of the address
segments and the postal code (if the postal code exists). The Street Address can consist of address elements
such as Street Number, Direction Prefix, StreetTypePrefix, Street Name, StreetTypeSuffix, and DirectionSuffix.
The sequence of these elements can vary for different countries.
If only one item is specified between the Street Address and Postal Code, it is treated as the CountrySubdivision.
If the Municipality and CountrySubdivision segments do not exist in the Free Form Address, the Postal Code must
be provided.
The following are some examples of valid USA Free Form Addresses:
Address with street address, city, state and postal code:

10 wall St., New York, NY; 10005

Address with street address, city and state:

10 wall St., New York, NY

Address with street address and city:

10 Wall St., NY
Address with street address and postal code:

10 wall St.; 10005

Formatted Address
The Formatted Address is defined using a unique element for each of the segments that make up the address.
The Formatted Address can be either a StreetAddress or StreetIntersection.
A description of the format for a StreetAddress and StreetIntersection can be found in the schema or SDK. For
both a StreetAddress or StreetIntersection you can specify the country subdivision, country secondary
subdivision, municipality, and municipality subdivision elements
Both of these two formatted address may also have a Postal Code. If there is no country subdivision or
municipality specified in the Formatted Address, the Postal Code is required. If the address contains only the
Postal Code, a Postal Code centroid geocoding is performed.

Inputs and Behavior

A request contains two key elements in order to obtain the geocoded location of an address:
Input

Required Description

Address

Yes

The Address element is specified at the location to be geocoded. The address

consists of a FreeFormAddress, StreetAddress, CountrySubdivision, Municipality,

and/or PostalCode.
Geocode
Preferences

Yes

Geocode Preferences determine the level of accuracy and whether close matches
are to be returned. For a more detailed description on preferences refer to Location
Utility Preferences and Geocode Preferences.

Output
A response contains a list of geocoded address positions that match the specified address (based on the geocode
preferences). The list of geocoded addresses contains four key pieces of information:
Output

Description

Number Of
Addresses

The number of matching address positions found for the specified address in the request. The
number of addresses found is the number of GeocodeAddress elements returned.

Position

The geocoded position of the street address. This position consists of the geocoded point and
the spatial reference system name.

Address

The address specified in the request is returned with all available information. For example, if the
postal code was not specified in the request, and postal data is available for this street address,
this information is returned.

Geocode
MatchCode

Determines whether the position for the address is a close match. An accuracy of 0.0 indicates
that the position is a close match based on the specified preferences in the configuration. The
matchType determines what information has been matched for this address. For information
about matchTypes, seeAccuracy for Close Matches.

Java Code Samples

The following Java code sample geocodes a free form address (10 Wall St., New York, NY) and sets numerous
match restrictions.

//Create a free address

Address address = new Address("US");
address.setFreeFormAddress("10 Wall St., New York, NY");
//Create an Extended Geocoding request
GeocodeRequestEx requestEx = new GeocodeRequestEx(address);
Properties pref = new Properties();
pref.setProperty(GeocodeRequestEx.CLOSE_MATCHES_ONLY, "false");
pref.setProperty(GeocodeRequestEx.MUSTMATCH_MAIN_ADDR, "false");
//pref.setProperty(GeocodeRequestEx.MAX_RANGES, "10");
requestEx.setGeocodePreference(pref);
The following Java code sample geocodes a formatted street address (43 West 83rd Street) specifying the
country subdivision (NY) and the municipality (New York).

//Create a street address

Address address = new Address("USA");
StreetAddress streetAddress = new StreetAddress("43 West 83rd. Street");
address.setStreetAddress(streetAddress);
address.setCountrySubdivision("NY");
address.setMunicipality("New York");
//Create a Geocoding Street Address request
GeocodeRequest request = new GeocodeRequest(address);

.NET Code Sample

The following sample geocodes a free form street address (10 Wall St., New York, NY; 10005). The maximum
number of response candidates for this request is five (MaximumResponses = "5"). Only the close matches is
returned (GeocodePreference.KEY_closeMatchesOnly, "true"), and two street address numbers is returned
closest to the position (GeocodePreference.KEY_maxRanges, "2").

private static Request newFreeFormAddressGeocodeRequest()

{
GeocodeRequest gr = new GeocodeRequest();
//set request identifier
gr.RequestID = "R1";
//set the maximum number of candidates in the response
gr.MaximumResponses = "5";
//set geocoding preferences
GeocodePreference gp = new GeocodePreference();
gp.setProperty(GeocodePreference.KEY_closeMatchesOnly, "true");
gp.setProperty(GeocodePreference.KEY_maxRanges, "2");
gr.GeocodePreference = gp;
//set the address in the request
Address addr = new Address();
addr.CountryCode ="US";
addr.Addressee = "US Address";
addr.FreeFormAddress = "10 Wall St., New York, NY; 10005";
Address[] addrs = {addr} ;
gr.Address = addrs;
return gr;
}

XML Sample
The following sample geocodes a free form address (10 Wall St., New York, NY).

<_RequestParameters xsi:type="ns4:GeocodeRequestTypeEx" xmlns:ns4="http:/

/www.mapinfo.com/xls">
<Address countryCode="US" xsi:type="ns3:AddressType">
<freeFormAddress>10 Wall St., New York, NY</freeFormAddress>
</Address>
<ns4:GeocodePreference type="closeMatchesOnly">false</
ns4:GeocodePreference>
<ns4:GeocodePreference type="MustMatchMainAddr">false</
ns4:GeocodePreference>
</_RequestParameters>
The following sample geocodes a formatted street address (43 west 83rd Street) specifying the country
subdivision (NY) and the municipality (New York).

<_RequestParameters xsi:type="ns2:GeocodeRequestType">
<Address countryCode="USA" xsi:type="ns2:AddressType">
<StreetAddress xsi:type="ns2:StreetAddressType">
<Street xsi:type="ns2:StreetNameType">43 West 83rd.
Street</
Street>
</StreetAddress>
<Place type="CountrySubdivision"
xsi:type="ns2:NamedPlaceType">NY</
Place>
<Place type="Municipality" xsi:type="ns2:NamedPlaceType">New
York</
Place>
</Address>
</_RequestParameters>

 2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com

Interpolating Address Points

By default, when you try to geocode an address, Envinsa estimates the location of the address based on the
street numbers at either end of street segment. For example, if a street segment runs from 100 Main St. to 200
Main St., then a request for 150 Main St. will return a location in the middle of the segment. This match

If you have a point user dictionary, such as ParcelPrecision, then Envinsa can use these known addresses to
further refine geocode results. This process is called Address Point Interpolation. Continuing the previous
example, suppose we use Address Point Interpolation and the geocoder finds the position of 180 Main St. in the
ParcelPrecision user dictionary, which is about two-thirds of the way down the street. Now, the geocoder can
estimate the position of our target address based on 100 and 180 Main St. In this case, the geocoder estimates
the location of the address slightly away from the center of the segment.

If you do not have a point user dictionary, then there is no benefit to using address point interpolation. The
standard Envinsa geocode data does not include enough address points to support this feature.
By default, address point interpolation is disabled for geocode requests. The following examples demonstrate how
you can enable this feature.

2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com

Java Code Sample

To use Address Point Interpolation with the Java SDK, you must set
the GeocodeRequestEx.USE_ADDRESSPOINT_INTERPOLATION property to true.
The following example geocodes an address using address point interpolation:

public Request createRequestEx()

{
//Create a street address
Address address = new Address("USA");
StreetAddress streetAddress = new StreetAddress("607 Myrtle Ave");
address.setStreetAddress(streetAddress);
address.setCountrySubdivision("NY");
address.setMunicipality("Albany");
address.setPostalCode("12208-3306");
// Create a Geocoding Street Address request
GeocodeRequestEx requestEx = new GeocodeRequestEx(address);
Properties prefs = new Properties();
prefs.setProperty(GeocodeRequestEx.CLOSE_MATCHES_ONLY, "true");
prefs.setProperty(GeocodeRequestEx.MUSTMATCH_ADDR_NUM, "true");
prefs.setProperty(GeocodeRequestEx.MUSTMATCH_MAIN_ADDR, "true");
prefs.setProperty(GeocodeRequestEx.MUSTMATCH_COUNTRY_SUBDIVISION,
"true");
prefs.setProperty(GeocodeRequestEx.MUSTMATCH_MUNICIPALITY, "true");
prefs.setProperty(GeocodeRequestEx.MUSTMATCH_POSTAL_CODE, "true");
// use address point interpolation.
prefs.setProperty(GeocodeRequestEx.USE_ADDRESSPOINT_INTERPOLATION,
"true");
requestEx.setGeocodePreference(prefs);
return requestEx;
}
2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com

.NET Code Sample

To use Address Point Interpolation with the .NET SDK, you must set
the GeocodePreference.KEY_useAddressPointInterpolation property to true.
The following example geocodes an address using address point interpolation:

private static Request newAddressInterpolationRequest()

{
GeocodeRequest gr = new GeocodeRequest();
//set request identifier
gr.RequestID = "R1";
//set the maximum number of candidates in the response
gr.MaximumResponses = "10";
//set geocoding preferences to use address point interpolation
GeocodePreference gp = new GeocodePreference();
gp.setProperty(GeocodePreference.KEY_closeMatchesOnly, "false");
gp.setProperty(GeocodePreference.KEY_useAddressPointInterpolation,
"true");
gr.GeocodePreference = gp;
//set the address in the request
Address addr = new Address();
addr.CountryCode ="US";
addr.Addressee = "US Address";
StreetAddress streetAddress = new StreetAddress();
streetAddress.Value = "607 Myrtle Ave";
addr.StreetAddress = streetAddress;
addr.CountrySubdivision = "NY";
addr.Municipality = "Albany";
addr.PostalCode = "12208-3306";
Address[] addrs = {addr} ;
gr.Address = addrs;
return gr;
}
2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com

Geocoding a Street Intersection

The Location Utility Service can geocode street intersections. These street intersections could be made up of
different address types or address elements, and the request may have different levels of accuracy or
preferences.

Inputs and Behaviors

The request contains three key elements in order to obtain the geocoded location of a street intersection:
Input

Required Description

Address

Yes

The Address specifies the location of the street intersection. To determine the position
of the street intersection the address requires the Country Subdivision and
Municipality where the two streets are located.

Street

Yes

One of the streets for the intersection.

Intersecting
Street

Yes

The other street for the street intersection.

Output
The response for a street intersection geocode request contains a list of geocoded street intersection positions.
The list of geocoded addresses contains three key pieces of information:
Output

Description

Number of
Addresses

The number of matching street intersection positions found for the specified addresses in the
request. The number of intersections found is the number of Geocode Address objects returned.

Position

The geocoded position of the street intersection. This position consists of the geocoded point
and the spatial reference system name.

Address

The address specified in the request is returned with all available information for the street
intersection. The number for each street at the intersection is returned, as well as the postal
code for the two street addresses.

Java Code Sample

The following example finds the geocoded position for the intersection of "Wall St." and "William St." in New York
City. The first street is defined using setStreetAddress, while the intersecting street is defined using
setIntersectingStreetAddress.

public Request createRequest() throws Exception

{
//Create an intersection address
Address address = new Address("USA");
StreetAddress st
= new StreetAddress("Wall St.");
StreetAddress intSt = new StreetAddress("William St.");
address.setStreetAddress(st);
address.setIntersectingStreetAddress(intSt);
address.setCountrySubdivision("NY");
address.setMunicipality("New York");
//Create a Geocoding Intersection Address request
GeocodeRequest request = new GeocodeRequest(address);

return request;
}

.NET Code Sample

The following example finds the geocoded position for the intersection of "Wall St." and "William St." in New York
City. Both streets are defined using StreetAddress, then added to IntersectingStreetAddress to make the street
intersection.

private static Request newStreetIntersectionGeocodeRequest()

{
GeocodeRequest gr = new GeocodeRequest();
//set request identifier
gr.RequestID = "R4";
//set the maximum number of candidates in the response
gr.MaximumResponses = "5";
//set the address intersection in the request
Address addr = new Address();
addr.CountryCode ="US";
addr.Municipality ="New York";
addr.CountrySubdivision ="NY";
StreetAddress[] saddrs = new StreetAddress[2] ;
saddrs[0] = new StreetAddress("Wall St.");
saddrs[1] = new StreetAddress("William St.");

addr.IntersectingStreetAddress =
Address[] addrs = {addr} ;
gr.Address = addrs;
return gr;

saddrs;

XML Sample
The following example finds the geocoded position for the intersection of "Wall St." and "William St." in New York
City. The first street is defined using Street element, while the intersecting street is defined using
IntersectingStreet element.

<_RequestParameters xsi:type="ns2:GeocodeRequestType">
<Address countryCode="USA" xsi:type="ns2:AddressType">
<StreetAddress xsi:type="ns2:StreetAddressType">
<Street xsi:type="ns2:StreetNameType">Wall
St.</Street>
<Street xsi:type="ns2:StreetNameType">William
St.</Street>
</StreetAddress>
<Place type="CountrySubdivision"
xsi:type="ns2:NamedPlaceType">NY</
Place>
<Place type="Municipality" xsi:type="ns2:NamedPlaceType">New
York</
Place>
</Address>
</_RequestParameters>
2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com

Geocoding a Postal Code Centroid

The Location Utility Service can geocode postal codes.

Inputs and Behaviors

The request contains one key element in order to obtain the geocoded location of a postal code centroid:
Input

Required Description

Address Yes

The Address specifies the postal code being geocoded. To determine the position of a
postal code centroid the address requires the Country code be specified.

Java Code Sample

The following example finds the geocoded centroid for the US postal code "10005".

public Request createRequest() throws Exception {

//Create a postal code address
Address address = new Address("USA");
address.setPostalCode("10005");
//Create a Geocoding Postal Address request
GeocodeRequest request = new GeocodeRequest(address);
return request;
}

.NET Code Sample

The following example finds the geocoded centroid for the US postal code "10005".

private static Request newPostalCodeAddressGeocodeRequest()

{
GeocodeRequest gr = new GeocodeRequest();
//set request identifier
gr.RequestID = "R2";
//set the maximum number of candidates in the response
gr.MaximumResponses = "3";
//set the address in the request
Address addr = new Address();
addr.CountryCode = "US";
addr.PostalCode = "10005";
Address[] addrs = {addr} ;
gr.Address = addrs;
return gr;
}

XML Sample
The following example finds the geocoded centroid for the US postal code "10005".

<_RequestParameters xsi:type="ns2:GeocodeRequestType">
<Address addressee="US Addressee" countryCode="US">
<PostalCode>10005</PostalCode>
</Address>
</_RequestParameters>
2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com

Geocoding a Point of Interest from a Place Code

The Location Utility Service can geocode specific Points of Interest (POIs) using the name and place code of the
POI.

Inputs and Behaviors

The request contains the following key elements in order to obtain the geocoded location of a point of interest
from a place code:
Input

Required Description

Country
Code

Yes

Specifying the country directs the query to the correct geocoding engine

Name of the
POI

Yes

The full name of the point of interest.

Place Code

Yes

The place code of the point of interest. Place codes are also referred to as miCodes
and more information can be found in the Data Guide found
at http://www.envinsa.com.
Some examples of commonly used miCodes are as follows:

Airports
Educational / Schools
Hospital / Polyclinic
Park
Shopping Malls / Shopping Center
Sports Center / Stadium

10310000
10210000
10230100
10130201
10010900
10120100

Country
Subdivision

No

Including the country subdivision helps to avoid unwanted results

Municipality

No

Including the name of the municipality helps to avoid unwanted results.

Output
The response for a point of interest from a place code request contains:
Output

Description

SRS

Name of the spatial reference system used for the location point.

Number of POIs Found

The number of matching POIs positions found for the request.

Location

For each POI found, the Lat/Long position is returned.

Country Code

For each POI found, the country code is returned.

Name of the POI

The full name of the point of interest.

Place Code

The place code of the point of interest.

Country Subdivision

The country subdivision of the point of interest.

Country Secondary Subdivision

The country secondary subdivision of the POI is returned.

Municipality

The name of the municipality in which the POI is located.

Java Code Sample

The following example finds the school called Lowell School in Teaneck, New Jersey.

AddressEx address = new AddressEx("USA");

address.setCountrySubdivision("New Jersey");
address.setMunicipality("Teaneck");
PlaceCode[] pcs = new PlaceCode[1];
pcs[0] = new PlaceCode("FCode");
// 10210000 is the code for school.
pcs[0].setValue("10210000");
address.setPlaceCode(pcs);
address.setPlaceName("Lowell School");
//Create a Gazetteer request
GeocodeRequest request = new GeocodeRequest(address);

XML Sample
The following example finds the school called Lowell School in Teaneck, New Jersey.

<_RequestParameters xsi:type="ns2:GeocodeRequestType">
<Address countryCode="USA" xsi:type="ns3:AddressTypeEx"
xmlns:ns3="http://www.mapinfo.com/xls">
<Place type="CountrySubdivision"
xsi:type="ns2:NamedPlaceType">New
Jersey</Place>
<Place type="Municipality"
xsi:type="ns2:NamedPlaceType">Teaneck</
Place>
<ns3:PlaceCode type="FCode">10210000</ns3:PlaceCode>
<ns3:PlaceName>Lowell School</ns3:PlaceName>
</Address>
</_RequestParameters>
2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com

Parsed versus Unparsed Street Addresses

After a successful geocode request, the service returns a response which includes the address submitted in the
request, as well as the desired response, the XY coordinate.
There are a few ways that an address can be expressed in both the requests and the responses. These methods
can be referred to as Parsed and Unparsed. While addresses can be included in requests as either parsed or
unparsed, the response always contains the unparsed version of the address (geocode responses also include
the parsed address). Both versions of the address are equivalent. Depending on the particular client
implementation, there may be advantages of using one method over the other.

2007 MapInfo Corporation. All rights reserved.

Email: docs@mapinfo.com