Geocode service GeocodeAddresses method

Geocodes multiple addresses and returns a single match result for each address.

GeocodeAddresses(RecordSet AddressTable, PropertySet AddressFieldMapping, PropertySet PropMods)

Parameter	Description
AddressTable	A RecordSet containing the addresses to be geocoded. Each record (row) stores a single address. It must contain a field for each address field defined by the geocode service and an OID field to store a unique ID.
AddressFieldMapping	Defines the mapping of address fields used by the geocode service to input fields in the AddressTableRecordSet.
PropMods	Modifications to the geocode service properties. Use GetLocatorProperties() to get a list of default locator properties. Use GetLocatorProperties() to return default locator properties.

Return Value

A RecordSet containing the best match for each input address based on the highest score. The names of the fields in the RecordSet are defined by the names of the fields returned by the GetResultFields() method. If a geocode service finds two or more matches that have the same highest match score, you can specify whether or not to match an address arbitrarily using the MatchIfScoresTie property of the locator. See the PropMods discussion below for more information on modifying geocode service (locator) properties.

Remarks

The following diagram illustrates the geocode server proxy methods commonly used when working with the GeocodeAddresses() method. In addition, the diagram also includes the input (address) and output (match) information one can expect when using this method.

The AddressTable parameter is a RecordSet containing the addresses to be geocoded. To create the AddressTable, first create a RecordSet object and each Field object. A number of fields must be included. A field named "OID" must be defined and will be used to store a unique id of each address match. Also, a field for each address field defined by the geocode service (returned using the GetAddressFields() method) must be included. In addition, each field must define a value for the Name, Length, and Type properties. To add an input address to AddressTable , create a new Record and set the Values property to an object array of comma delimited values. Add the fields using the RecordSet.Fields property and add the records using the RecordSet.Records property.

The AddressFieldMapping parameter defines the mapping of address fields used by the geocode service to input fields in the AddressTable RecordSet. The names of the properties in this PropertySet are the names of the address fields used by the geocode service. Use the GetAddressFields() method to get the set of fields used by the geocode service.

The PropMods parameter is a PropertySet containing the geocode service properties to use to find candidates for the address. The GetLocatorProperties() method returns the set of default geocoding properties for the geocode service. In some cases, you may want to modify the geocoding properties used to determine the best location for an address. For example, you may wish to change the spelling sensitivity used to search for a match for the address, or you may want to change the side and end offset applied to the geocoded location. Modify the properties in the PropertySet returned by the GetLocatorProperties() method and pass the modified object as the PropMods parameter. It only needs to contain properties that are different than the default properties for the geocode service. If you do not need to modify any of the default properties returned used by the geocode service, the PropMods parameter can be null or you can pass the unmodified PropertySet returned by the GetLocatorProperties() method.

Examples

C#

Note:

In order to set the referer in the request, you must override the GetWebRequest method. This is handled in the first portion of the sample below. For more information, see Modifying HTTP request properties.

namespace SOAP_Samples.GeocodeService
{
  public partial class World_GeocodeServer
  {
    // Override the GetWebRequest method of the Web Reference to additionally
    // pass in the referer used to generate the token
    protected override System.Net.WebRequest GetWebRequest(Uri uri)
    {
      System.Net.HttpWebRequest webRequest = (System.Net.HttpWebRequest)base.GetWebRequest(uri);
      webRequest.Referer = "myReferer";
      return webRequest;
    }
  }
}

namespace SOAP_Samples
{
  

  public partial class Form1 : Form
  {
    public Form1()
    {
      InitializeComponent();
    }



    private void button1_Click(object sender, EventArgs e)
    {
      GeocodeAddresses();
    }
    
    private void GeocodeAddresses()
    {
      string username = "org_username";
      string password = "org_password";
      string referer = "myReferer";

      // Get token service
      string tokenServiceURL;
      HttpWebRequest request = (HttpWebRequest)HttpWebRequest.CreateDefault(new Uri("http://geocode.arcgis.com/arcgis/rest/info?f=pjson"));
      HttpWebResponse response = (HttpWebResponse)request.GetResponse();
      Stream responseStream = response.GetResponseStream();
      using (StreamReader reader = new StreamReader(responseStream))
      {
        string responseText = reader.ReadToEnd();

        int startPos = responseText.IndexOf("tokenServicesUrl") + 20;
        int endPos = responseText.IndexOf("\"", startPos);
        tokenServiceURL = responseText.Substring(startPos, endPos - startPos);

        reader.Close();
      }
      responseStream.Close();
      response.Close();

      // Get token
      string token;
      request = (HttpWebRequest)HttpWebRequest.CreateDefault(new Uri(tokenServiceURL + "?f=json&expiration=60" + 
		              "&username=" + username + "&password=" + password + "&referer=" + referer));
      response = (HttpWebResponse)request.GetResponse();
      responseStream = response.GetResponseStream();
      using (StreamReader reader = new StreamReader(responseStream))
      {
        string responseText = reader.ReadToEnd();
        if ((responseText.Length == 0) || (responseText.IndexOf("error") > -1))
        {
          MessageBox.Show("Error getting token.");
          return;
        }

        int startPos = 12;
        int endPos = responseText.IndexOf("\"", startPos);
        token = responseText.Substring(startPos, endPos - startPos);

        reader.Close();
      }
      responseStream.Close();
      response.Close();


      // Setup geocoding service with new token
      World_GeocodeServer geocodeservice = new World_GeocodeServer();
      geocodeservice.Url = "http://geocode.arcgis.com/arcgis/services/World/GeocodeServer?token=" + token;


      // Create property set to map locator address fields (key) to fields in the input
      // address table (value).  In this example they are the same.
      PropertySet geocodePropSet = new PropertySet();
      PropertySetProperty[] propArray = new PropertySetProperty[2];

      PropertySetProperty geocodeProp = new PropertySetProperty();
      geocodeProp.Key = "Address";
      geocodeProp.Value = "Address";
      propArray[0] = geocodeProp;
      
      PropertySetProperty geocodeProp1 = new PropertySetProperty();
      geocodeProp1.Key = "Postal";
      geocodeProp1.Value = "Postal";
      propArray[1] = geocodeProp1;

      geocodePropSet.PropertyArray = propArray;

      // Create a new recordset to store input addresses to be batch geocoded
      RecordSet addressTable = new RecordSet();
      Field[] fieldarray = new Field[3];

      // Following field properties are required for batch geocode to work:
      // Length, Name, Type.  There also needs to be a field of type OID.
      Field field0 = new Field();
      field0.Name = "OID";
      field0.Type = esriFieldType.esriFieldTypeOID;
      field0.Length = 50;
      fieldarray[0] = field0;
      
      Field field1 = new Field();
      field1.Name = "Address";
      field1.Type = esriFieldType.esriFieldTypeString;
      field1.Length = 50;
      fieldarray[1] = field1;
      
      Field field2 = new Field();
      field2.Name = "Postal";
      field2.Type = esriFieldType.esriFieldTypeString;
      field2.Length = 50;
      fieldarray[2] = field2;
      
      Fields fields = new Fields();
      fields.FieldArray = fieldarray;
      addressTable.Fields = fields;
      
      // Add records to input address table
      Record[] records = new Record[2];
      
      Record record1 = new Record();
      record1.Values = new object[3] { 0, "5950 Magnolia Ave.", "92506" };
      records[0] = record1;
      
      Record record2 = new Record();
      record2.Values = new object[3] { 1, "5962 Magnolia Ave.", "92506" };
      records[1] = record2;
      
      addressTable.Records = records;

      // Make the request to the geocoding service to geocode the addresses
      RecordSet results = geocodeservice.GeocodeAddresses(addressTable, geocodePropSet, null);

      // Output the results
      if (results != null)
      {
        StringBuilder sb = new StringBuilder();
        string valuesoutput = string.Empty;
        foreach (Record record in results.Records)
        {
          foreach (object value in record.Values)
          {
            sb.Append(value);
            sb.Append("\t");
          }
          sb.AppendLine();
        }
        MessageBox.Show(sb.ToString());
      }
    }
  }
}

VB.NET

Dim geocodeservice As GeocodeService_GeocodeServer = New GeocodeService_GeocodeServer()

geocodeservice.Url = "http://localhost:6080/arcgis/services/GeocodeService/GeocodeServer"

 

' Create property set to map locator address fields (key) to fields in the input

' address table (value). In this example they are the same.

Dim geocodePropSet As PropertySet = New PropertySet()

Dim propArray(1) As PropertySetProperty

Dim geocodeProp As PropertySetProperty = New PropertySetProperty()

geocodeProp.Key = "Street"

geocodeProp.Value = "Street"

propArray(0) = geocodeProp

 

Dim geocodeProp1 As PropertySetProperty = New PropertySetProperty()

geocodeProp1.Key = "Zone"

geocodeProp1.Value = "Zone"

propArray(1) = geocodeProp1

 

geocodePropSet.PropertyArray = propArray

 

' Create a new recordset to store input addresses to be batch geocoded

Dim addressTable As RecordSet = New RecordSet()

 

' Create fields for input address table

Dim fieldarray(2) As Field

 

' Following field properties are required for batch geocode to work:

' Length, Name, Type. There also needs to be a field of type OID.

Dim field0 As Field = New Field()

field0.Name = "OID"

field0.Type = esriFieldType.esriFieldTypeOID

field0.Length = 50

fieldarray(0) = field0

 

Dim field1 As Field = New Field()

field1.Name = "Street"

field1.Type = esriFieldType.esriFieldTypeString

field1.Length = 50

fieldarray(1) = field1

 

Dim field2 As Field = New Field()

field2.Name = "Zone"

field2.Type = esriFieldType.esriFieldTypeString

field2.Length = 50

fieldarray(2) = field2

 

Dim fields As Fields = New Fields()

fields.FieldArray = fieldarray

addressTable.Fields = fields

 

' Add records to input address table

Dim records(1) As Record

Dim record1 As Record = New Record()

record1.Values = New Object(2){0, "5950 Magnolia Ave.", "92506" }

records(0) = record1

 

Dim record2 As Record = New Record()

record2.Values = New Object(2) {1, "5962 Magnolia Ave.", "92506"}

records(1) = record2

 

addressTable.Records = records

 

' Generate results table

Dim results as RecordSet = geocodeservice.GeocodeAddresses(addressTable, geocodePropSet,Nothing)

If Not results Is Nothing Then

      Dim fieldsoutput As String = String.Empty

      Dim fieldResult As Field

 

      For Each fieldResult In results.Fields.FieldArray

            fieldsoutput += fieldResult.Name + vbTab

      Next

 

      Dim record As Record

      For Each record In results.Records

            Dim valuesoutput As String = String.Empty

            Dim values() As Object = record.Values

            Dim v As Integer = 0

            Dim fieldresult2 As Field

 

            For Each fieldresult2 In results.Fields.FieldArray

                  valuesoutput += values(v).ToString() + vbTab

                  v = v + 1

            Next

      Next

End If

Java

import java.io.IOException;
import com.esri.arcgisws.*;

public class GeocodeAddressesClass {


public static void main(String[] args) {
	
	try {

		GeocodeAddresses();
		}
	catch (Exception ex) {
		ex.printStackTrace();
	}
}

public static void GeocodeAddresses() throws IOException {

	String username = "username";
	String password = "password";
	String url = "http://EXAMPLE:6080/arcgis/services/AtlantaStreets/GeocodeServer";


	// Setup geocoding service with new token
	GeocodeServerBindingStub geocodeService = new GeocodeServerBindingStub(url, username, password);

	// Create property set to map locator address fields (key) to fields in the input
	// address table (value).  In this example they are the same.
	PropertySetProperty geocodeProp1 = new PropertySetProperty();
	geocodeProp1.setKey("Street");
	geocodeProp1.setValue("Street");		 

	PropertySetProperty geocodeProp2 = new PropertySetProperty();
	geocodeProp2.setKey("Zip");
	geocodeProp2.setValue("Zip");

	PropertySetProperty[] propArray = new PropertySetProperty[2];
	propArray[0] = geocodeProp1;
	propArray[1] = geocodeProp2;
	
	PropertySet geocodePropSet = new PropertySet();
	geocodePropSet.setPropertyArray(propArray);


	//Create a new recordset to store input addresses to be batch geocoded
	RecordSet addressTable = new RecordSet();	
	Field[] geocodeServiceFields = geocodeService.getAddressFields().getFieldArray();
	Field[] fieldArray = new Field[3];
	
	fieldArray[0] = new Field();
	fieldArray[0].setName("OID");
	fieldArray[0].setType(EsriFieldType.esriFieldTypeOID);
	fieldArray[0].setLength(50);

	fieldArray[1] = findField(geocodeServiceFields, "Street");
	fieldArray[2] = findField(geocodeServiceFields, "ZIP");

	Fields fields = new Fields();
	fields.setFieldArray(fieldArray);		 
	
	addressTable.setFields(fields);	   
	
	//Add records to input address table
	Record[] records = new Record[2];
	Record record1 = new Record();
	Record record2 = new Record();
	record1.setValues (new Object[] {1, "30 Marietta St", "30303"});
	record2.setValues (new Object[] {2, "55 Trinity Avenue", "30303"});
	records[0]=record1;
	records[1]=record2;		 
	
	addressTable.setRecords(records);
	
	// Make the request to the geocoding service to geocode the addresses

	RecordSet results = geocodeService.geocodeAddresses(addressTable, geocodePropSet, null);
	// Output the results
	for (Record record : results.getRecords()) {
		StringBuilder sb = new StringBuilder();
		for (Object value : record.getValues()) {
			if (value instanceof PointN) {
				PointN pt = (PointN) value;
				sb.append(pt.getX() + "," + pt.getY() + "\t");
			}
			else {
				sb.append(value + "\t");
			}
		}  
		System.out.println(sb);
	}

	
	Fields fieldsArray = geocodeService.getAddressFields();
	for (Field f : fieldsArray.getFieldArray()) {
		System.out.println(f.getName());
	}
}

public static Field findField(Field[] fields, String name) {
	for (Field f : fields) {
		if (f.getName().equals(name))
			return f;
	}
	return null;
}

}