RouteMAP IMS allows you to find several types of locations, depending on the map data. There are two special objects that provide such functionality: the FinderList and the Finder objects.

The USA data pack supports the following types of locations:
1) street address;
2) street intersection;
3) ZIP code;
4) city;
5) county;
6) area code;
7) location specified by its coordinates (lat/long).

Each location type has a corresponding finder, and each finder has one or more corresponding fields. You can find out what types of locations the map supports using this code (also see sample output: USA map / North American map).

When you know the type and all the corresponding fields, you can easily find the location. For example, if you're trying to find a US address, the US address finder number is 0 and there are four fields: Address, ZIP, City and State. Follow the steps below:

// get the FinderList object
FinderList Finders = map.getFinders();
// get the US address finder by number
Finder Finder = Finders.getFinder(0);

Finder.setFieldValueByName("Address", "1235 W Colton Ave");
Finder.setFieldValueByName("ZIP", "");   // you can specify either ZIP, or City and State
Finder.setFieldValueByName("City", "Redlands");
Finder.setFieldValueByName("State", "CA");

Recordset rs = Finder.find(); // this method returns the Recordset object


if( rs != null)
{
    int i=1;
	
    do
    {
        out.println( "<b>Location #" + i++ + "</b><br>");
		
        // see the Finder.find() method for details
        out.println( "name: " + rs.getAsStringByName("NAME") + "<br>");
        out.println( "score: " + rs.getAsIntByName("SCORE") + "<br>");
        out.println( "x: " + rs.getAsDoubleByName("X") + "<br>");
        out.println( "y: " + rs.getAsDoubleByName("Y") + "<br>");
        out.println( "latitude: " + rs.getAsDoubleByName("LAT") + "<br>");
        out.println( "longitude: " + rs.getAsDoubleByName("LONG") + "<br>");		
        
    } while(rs.moveNext());
}

Output:

Location #1
name: 1235 W Colton Ave, Redlands, CA 92374
score: 99
x: -1163.4475
y: 2356.175
latitude: 34.06288593364601
longitude: -117.20088705869182
Location #2
name: 1235 E Colton Ave, Redlands, CA 92374
score: 99
x: -1160.2775
y: 2356.1675
latitude: 34.06277750721567
longitude: -117.14312182908236

To find a different type of location, first identify the number of the finder to use and then fill in all the required fields for that specific finder.

An advanced version of the findLocation function can be found here.

You can also identify a point on the map by using the identify method of the Map interface. This method tries to find a feature on the map starting from the top layer.
See the example below:

<%
    Map map = openMap( application);

    Recordset idrs  = null;
    IdentifyResult idr  = null;
    
    if( request.getParameter("map.x") != null && request.getParameter("map.y") != null)
        idr = map.identify( Integer.parseInt( request.getParameter("map.x")), Integer.parseInt( request.getParameter("map.y")));

    if( idr != null)
        idrs = idr.getRecordset();
%>
<% if( idrs != null) {%>

<br>Layer: <%= map.getLayers().getLayer(idr.getLayerNumber()).getName() %><br>
<table>
<tr>

<%
    FieldDesc idFields = idrs.getFields();

    for( int i = 0; i < idFields.getFieldCount(); i++)
    {
        if( idFields.getFieldType(i) != FieldType.SHAPE)
            out.println("<th bgcolor='#C0C0C0'>" + idFields.getFieldName(i) + "</th>");
    }

    out.println("</tr>\n" );
    idrs.moveFirst();

    String val;
    
    while( ! idrs.IsEOF())
    {
        out.println("<tr bgcolor='#ECECEC'>");

        for( int i = 0; i < idFields.getFieldCount(); i++)
        {
            if( idFields.getFieldType(i) != FieldType.SHAPE)
            {
                val = idrs.getAsString(i);
                out.println("<td>" + val + "</td>");
            }
        }
        
        out.println("</tr>\n");
        idrs.moveNext();
    }
%>

</table>
<% } //end if  %>

<form>
<input type="image" name="map" src="<%= map.getMapImageURL(map.getImageWidth(), map.getImageHeight(), ImageFormat.DEFAULT)%>"
width="<%=map.getImageWidth()%>" height="<%=map.getImageHeight()%>">
</form>

Start this example and try to click on the map image.