How to geocode a single address


In this topic


Geocoding a single address

This topic discusses the following two ways to geocode a single address:
  • Using IAddressGeocoding and MatchAddress
  • Using a GeocodeServer

Using IAddressGeocoding and MatchAddress

The following is the primary way to geocode a single address:
  1. Once you have the locator, set the address parameters, then call MatchAddress. The address parameter is a PropertySet containing properties that represent the input address components used by the locator. Use the AddressFields property on the IAddressInputs interface to determine the input address components used by the locator.
  2. The MatchFields property of the address locator contains the coordinates of the points that match the address that was passed in. The MatchFields property returns a Field collections where the names of the Field objects correspond to the names of the properties in the PropertySet returned by the MatchAddress method.

    See the following code example:
[C#]
public void geocodeSingleAddress()
{
    // Open the file geodatabase.
    System.Object obj = Activator.CreateInstance(Type.GetTypeFromProgID(
        "esriDataSourcesGDB.FileGDBWorkspaceFactory"));
    IWorkspaceFactory2 workspaceFactory = obj as IWorkspaceFactory2;
    IWorkspace workspace = workspaceFactory.OpenFromFile(@"C:\UnitedStates.gdb", 0);

    // Get the locator workspace.
    obj = Activator.CreateInstance(Type.GetTypeFromProgID(
        "esriLocation.LocatorManager"));
    ILocatorManager2 locatorManager = obj as ILocatorManager2;
    ILocatorWorkspace locatorWorkspace = locatorManager.GetLocatorWorkspace
        (workspace);

    // Get the locator for the locator workspace.
    IAddressGeocoding addressGeocoding = (IAddressGeocoding)
        locatorWorkspace.GetLocator("USLocator");

    // Geocode the address using the locator
    IPropertySet addressProperties = new PropertySetClass();
    addressProperties.SetProperty("Street", "380 New York St");
    addressProperties.SetProperty("City", "Redland");
    addressProperties.SetProperty("State", "CA");
    addressProperties.SetProperty("ZIP", "92377");
    IPropertySet matchProperties = addressGeocoding.MatchAddress(addressProperties);

    // Print the match properties.
    IFields matchFields = addressGeocoding.MatchFields;
    IField matchField = new FieldClass();
    for (int i = 0; i < matchFields.FieldCount; i++)
    {
        matchField = matchFields.get_Field(i);
        if (matchField.Type == esriFieldType.esriFieldTypeGeometry)
        {
            IPoint point = (IPoint)matchProperties.GetProperty(matchField.Name);
            if (!point.IsEmpty)
            {
                Console.WriteLine("X: " + point.X);
                Console.WriteLine("Y: " + point.Y);
            }
        }
        else
        {
            Console.WriteLine(matchField.AliasName + ": " +
                matchProperties.GetProperty(matchField.Name));
        }
    }
}
[VB.NET]
Sub AddressGeocoding()
    ' Open a file geodatabase.
    Dim obj As System.Object = Activator.CreateInstance(Type.GetTypeFromProgID("esriDataSourcesGDB.FileGDBWorkspaceFactory"))
    Dim workspaceFactory As IWorkspaceFactory = obj
    Dim workspace As IWorkspace = workspaceFactory.OpenFromFile("C:\UnitedStates.gdb", 0)
    
    ' Open the locator workspace.
    obj = Activator.CreateInstance(Type.GetTypeFromProgID("esriLocation.LocatorManager"))
    Dim locatorManager As ILocatorManager = obj
    Dim locatorWorkspace As ILocatorWorkspace = locatorManager.GetLocatorWorkspace(workspace)
    
    ' Get a locator.
    Dim addressGeocoding As IAddressGeocoding = locatorWorkspace.GetLocator("USLocator")
    
    ' Set up the address properties.
    Dim addressProperties As IPropertySet = New PropertySet
    With addressProperties
        .SetProperty("Street", "380 New York St.")
        .SetProperty("City", "Redlands")
        .SetProperty("State", "CA")
        .SetProperty("ZIP", "92373")
    End With
    
    ' Geocode an address using the locator.
    Dim matchProperties As IPropertySet = addressGeocoding.MatchAddress(addressProperties)
    
    ' Print the match properties.
    Dim point As IPoint
    Dim matchField As IField
    Dim matchFields As IFields = addressGeocoding.MatchFields
    For matchFieldIndex As Long = 0 To matchFields.FieldCount - 1
        matchField = matchFields.Field(matchFieldIndex)
        If matchField.Type = ESRI.ArcGIS.Geodatabase.esriFieldType.esriFieldTypeGeometry Then
            point = matchProperties.GetProperty(matchField.Name)
            If Not point.IsEmpty Then
                Console.WriteLine("X: " & point.X)
                Console.WriteLine("Y: " & point.Y)
            End If
        Else
            Console.WriteLine(matchField.AliasName & ": " & matchProperties.GetProperty(matchField.Name))
        End If
    Next
End Sub

Using IAddressCandidates and FindAddressCandidates

The following is the way to return all of the address candidates for a single address:
  1. Once you have the locator, set the address parameters, then call FindAddressCandidates. The address parameter is a PropertySet containing properties that represent the input address components used by the locator. Use the AddressFields property on the IAddressInputs interface to determine the input address components used by the locator.
  2. The CandidateFields property of the address locator contains the fields that are returned for each candidate. You can use the fields returned by this property to inspect candidates found using the FindAddressCandidates method.

    See the following code example:
[C#]
public void AddressCandidates()
{
    // Get the Workspace
    System.Object obj = Activator.CreateInstance(Type.GetTypeFromProgID(
        "esriDataSourcesGDB.FileGDBWorkspaceFactory"));
    IWorkspaceFactory2 workspaceFactory = obj as IWorkspaceFactory2;
    IWorkspace workspace = workspaceFactory.OpenFromFile(@"C:\UnitedStates.gdb", 0);

    // Get the Locator and QI to IAddressCandidates2
    obj = Activator.CreateInstance(Type.GetTypeFromProgID(
        "esriLocation.LocatorManager"));
    ILocatorManager locatorManager = obj as ILocatorManager2;
    ILocatorWorkspace locatorWorkspace = locatorManager.GetLocatorWorkspace
        (workspace);
    ILocator locator = locatorWorkspace.GetLocator("USLocator");
    IAddressCandidates2 addressCandidates = locator as IAddressCandidates2;

    // Find the address candidates
    IPropertySet2 addressProperties = new PropertySetClass();
    addressProperties.SetProperty("Street", "380 New York St.");
    addressProperties.SetProperty("City", "Redlands");
    addressProperties.SetProperty("State", "CA");
    addressProperties.SetProperty("Zip", "92373");

    // Use the FindAddressCandidates method find candidates for an address
    IArray resultsArray = addressCandidates.FindAddressCandidates(addressProperties);

    // Use the CandidateFields property to display the properties of each candidate
    IFields candidateFields = addressCandidates.CandidateFields;
    IPropertySet2 candidatePropertySet = null;
    IField addressField = null;
    for (int candidateIndex = 0; candidateIndex < resultsArray.Count; candidateIndex
        ++)
    {
        candidatePropertySet = resultsArray.get_Element(candidateIndex)as
            IPropertySet2;
        for (int fieldIndex = 0; fieldIndex < candidateFields.FieldCount; fieldIndex
            ++)
        {
            addressField = candidateFields.get_Field(fieldIndex);
            if (addressField.Type != esriFieldType.esriFieldTypeGeometry)
            {
                Console.WriteLine(addressField.AliasName + ": " +
                    candidatePropertySet.GetProperty(addressField.Name));
            }
        }
        Console.WriteLine();
    }
}
[VB.NET]
Sub AddressCandidates()
    ' Get the Workspace
    Dim obj As System.Object = Activator.CreateInstance(Type.GetTypeFromProgID("esriDataSourcesGDB.FileGDBWorkspaceFactory"))
    Dim workspaceFactory As IWorkspaceFactory = obj
    Dim workspace As IWorkspace = workspaceFactory.OpenFromFile("C:\UnitedStates.gdb", 0)
    
    ' Get the Locator and QI to IAddressCandidates2
    obj = Activator.CreateInstance(Type.GetTypeFromProgID("esriLocation.LocatorManager"))
    Dim locatorManager As ILocatorManager = obj
    Dim locatorWorkspace As ILocatorWorkspace = locatorManager.GetLocatorWorkspace(workspace)
    Dim locator As ILocator = locatorWorkspace.GetLocator("USLocator")
    Dim addressCandidates As IAddressCandidates2 = locator
    
    ' Find the address candidates
    Dim addressProperties As IPropertySet2 = New PropertySetClass()
    addressProperties.SetProperty("Street", "380 New York St.")
    addressProperties.SetProperty("City", "Redlands")
    addressProperties.SetProperty("State", "CA")
    addressProperties.SetProperty("Zip", "92373")
    
    ' Use the FindAddressCandidates method find candidates for an address
    Dim resultsArray As IArray = addressCandidates.FindAddressCandidates(addressProperties)
    
    ' Use the CandidateFields property to display the properties of each candidate
    Dim candidateFields As IFields = addressCandidates.CandidateFields
    Dim candidatePropertySet As IPropertySet2
    Dim addressField As IField
    For candidateIndex As Integer = 0 To resultsArray.Count - 1
        candidatePropertySet = resultsArray.Element(candidateIndex)
        For fieldIndex As Integer = 0 To candidateFields.FieldCount - 1
            addressField = candidateFields.Field(fieldIndex)
            If (addressField.Type <> esriFieldType.esriFieldTypeGeometry) Then
                Console.WriteLine(addressField.AliasName + ": " + candidatePropertySet.GetProperty(addressField.Name).ToString())
            End If
        Next
        Console.WriteLine()
    Next
End Sub

Using ArcGIS Online locators

ArcGIS Online locators can be accesses programmatically by using the IAGSServerConnection interface and the ILocatorWorkspace interface to get the locator object.
Once the locator object has been retrieved, you can use IAddressCandidates, IAddressGeocoding, or IReverseGeocoding to perform geocoding operations against the ArcGIS Online locators.
See the following code example:
[C#]
public void LoadAGOLLocator()
{
    IPropertySet connectionProperties = new PropertySetClass();
    connectionProperties.SetProperty("Url", 
        "http://tasks.arcgisonline.com/arcgis/services");

    // Open a workspace with an ArcGIS Server connection
    System.Object obj = Activator.CreateInstance(Type.GetTypeFromProgID(
        "esriGISClient.AGSServerConnectionFactory"));
    IAGSServerConnectionFactory AGSServerConnectionFactory = obj as
        AGSServerConnectionFactory;
    IAGSServerConnection AGSServerConnection = AGSServerConnectionFactory.Open
        (connectionProperties, 0);

    // Get the locator workspace from the open workspace
    obj = Activator.CreateInstance(Type.GetTypeFromProgID(
        "esriLocation.LocatorManager"));
    ILocatorManager2 locatorManager = obj as ILocatorManager2;
    IAGSServerConnectionName agsServerConnectionName = AGSServerConnection.FullName
        as IAGSServerConnectionName;
    ILocatorWorkspace locatorWorkspace = locatorManager.GetAGSLocatorWorkspace
        (agsServerConnectionName);
    ILocator AGOLLocator = locatorWorkspace.GetLocator("Locators/TA_Address_NA");

    // Get the address inputs for the locator
    IAddressInputs addressInputs = AGOLLocator as IAddressInputs;
    IFields addressFields = addressInputs.AddressFields;
    int fieldCount = addressFields.FieldCount;
    String[] addressFieldNames = new String[fieldCount];
    for (int i = 0; i < fieldCount; i++)
    {
        addressFieldNames[i] = addressFields.get_Field(i).Name;
    }

    // Set the Address that will be geocoded
    IPropertySet addressProperties = new PropertySetClass();
    addressProperties.SetProperty(addressFieldNames[0], "380 New York St");
    addressProperties.SetProperty(addressFieldNames[1], "Redlands");
    addressProperties.SetProperty(addressFieldNames[2], "CA");
    addressProperties.SetProperty(addressFieldNames[3], "92377");

    // Find the address candidates
    IAddressCandidates addressCandidates = AGOLLocator as IAddressCandidates;
    IArray resultsArray = addressCandidates.FindAddressCandidates(addressProperties);

    // Use the CandidateFields property to display the properties of each candidate
    IFields candidateFields = addressCandidates.CandidateFields;
    IPropertySet2 candidatePropertySet = null;
    IField addressField = null;
    for (int candidateIndex = 0; candidateIndex < resultsArray.Count; candidateIndex
        ++)
    {
        candidatePropertySet = resultsArray.get_Element(candidateIndex)as
            IPropertySet2;
        for (int fieldIndex = 0; fieldIndex < candidateFields.FieldCount; fieldIndex
            ++)
        {
            addressField = candidateFields.get_Field(fieldIndex);
            if (addressField.Type != esriFieldType.esriFieldTypeGeometry)
            {
                Console.WriteLine(addressField.AliasName + ": " +
                    candidatePropertySet.GetProperty(addressField.Name));
            }
        }
        Console.WriteLine();
    }
}
[VB.NET]
Public Sub LoadAGOLLocator()
    Dim connectionProperties As IPropertySet = New PropertySetClass()
    connectionProperties.SetProperty("Url", "http://tasks.arcgisonline.com/arcgis/services")
    
    ' Open a workspace with an ArcGIS Server connection
    Dim obj As System.Object = Activator.CreateInstance(Type.GetTypeFromProgID("esriGISClient.AGSServerConnectionFactory"))
    Dim AGSServerConnectionFactory As IAGSServerConnectionFactory = obj
    Dim AGSServerConnection As IAGSServerConnection = AGSServerConnectionFactory.Open(connectionProperties, 0)
    
    ' Get the locator workspace from the open workspace
    obj = Activator.CreateInstance(Type.GetTypeFromProgID("esriLocation.LocatorManager"))
    Dim locatorManager As ILocatorManager2 = obj
    Dim agsServerConnectionName As IAGSServerConnectionName = AGSServerConnection.FullName
    Dim locatorWorkspace As ILocatorWorkspace = locatorManager.GetAGSLocatorWorkspace(agsServerConnectionName)
    Dim AGOLLocator As ILocator = locatorWorkspace.GetLocator("Locators/TA_Address_NA")
    
    ' Get the address inputs for the locator
    Dim addressInputs As IAddressInputs = AGOLLocator
    Dim addressFields As IFields = addressInputs.AddressFields
    Dim fieldCount As Integer = addressFields.FieldCount
    Dim addressFieldNames(fieldCount) As String
    For i As Integer = 0 To fieldCount - 1
        addressFieldNames(i) = addressFields.Field(i).Name
    Next
    
    ' Set the Address that will be geocoded
    Dim addressProperties As IPropertySet = New PropertySetClass()
    addressProperties.SetProperty(addressFieldNames(0), "380 New York St")
    addressProperties.SetProperty(addressFieldNames(1), "Redlands")
    addressProperties.SetProperty(addressFieldNames(2), "CA")
    addressProperties.SetProperty(addressFieldNames(3), "92377")
    
    ' Find the address candidates
    Dim addressCandidates As IAddressCandidates = AGOLLocator
    Dim resultsArray As IArray = addressCandidates.FindAddressCandidates(addressProperties)
    
    ' Use the CandidateFields property to display the properties of each candidate
    Dim candidateFields As IFields = addressCandidates.CandidateFields
    Dim candidatePropertySet As IPropertySet2
    Dim addressField As IField
    For candidateIndex As Integer = 0 To resultsArray.Count - 1
        candidatePropertySet = resultsArray.Element(candidateIndex)
        For fieldIndex As Integer = 0 To candidateFields.FieldCount - 1
            addressField = candidateFields.Field(fieldIndex)
            If addressField.Type <> esriFieldType.esriFieldTypeGeometry Then
                Console.WriteLine(addressField.AliasName & ": " & candidatePropertySet.GetProperty(addressField.Name))
            End If
            Console.WriteLine()
        Next
    Next
End Sub

Using a GeocodeServer

A GeocodeServer is a ServerObject delivered by an ArcGIS Server that can be used to geocode addresses. Internally, a GeocodeServer uses an address locator to do the geocoding and exposes the high-level functionality of the address locator using the IGeocodeServer interface. 
Generally, GeocodeServer objects are used by ArcGIS Server developers to create server applications that include geocoding functionality. However, ArcGIS Desktop and ArcGIS Engine developers can use GeocodeServer objects to include geocoding functionality in ArcGIS Desktop customizations, and custom applications using only the high-level geocoding functionality exposed by a GeocodeServer.
See the following code example:
[C#]
public void GeocodeSingleAddressOnGeocodeServer()
{
    // Open a GISServerConnection.
    IGISServerConnection gisServerConnection = new GISServerConnectionClass();
    gisServerConnection.Connect("AGSServer");

    // Get a GeocodeServer from the GISServerConnection.
    IServerObjectManager serverObjectManager =
        gisServerConnection.ServerObjectManager;
    IServerContext serverContext = serverObjectManager.CreateServerContext(
        "California", "GeocodeServer");
    IServerObject serverObject_GeocodeServer = serverContext.ServerObject;
    IGeocodeServer geocodeServer = (IGeocodeServer)serverObject_GeocodeServer;

    // Construct an address PropertySet to geocode.
    IPropertySet addressProperties = (IPropertySet)serverContext.CreateObject(
        "esriSystem.PropertySet");
    addressProperties.SetProperty("Street", "380 New York St.");
    addressProperties.SetProperty("City", "Redlands");
    addressProperties.SetProperty("State", "CA");
    addressProperties.SetProperty("ZIP", "92373");

    // Set the geocoding properties to use to geocode the address.
    IPropertySet locatorProperties = geocodeServer.GetLocatorProperties();
    locatorProperties.SetProperty("MinimumMatchScore", "100");
    locatorProperties.SetProperty("SpellingSensitivity", "100");

    // Geocode the address.
    IPropertySet resultSet = geocodeServer.GeocodeAddress(addressProperties,
        locatorProperties);

    // Print the match properties.
    IFields fields = geocodeServer.GetResultFields(null);
    IField field = null;
    IPoint point = null;
    for (int i = 0; i < fields.FieldCount; i++)
    {
        field = fields.get_Field(i);
        object fieldValue = resultSet.GetProperty(field.Name);
        if (field.Type == esriFieldType.esriFieldTypeGeometry)
        {
            point = (IPoint)fieldValue;
            if (!point.IsEmpty)
            {
                Console.WriteLine("X: " + point.X);
                Console.WriteLine("Y: " + point.Y);
            }
        }
        else
            Console.WriteLine(field.AliasName + ": " + fieldValue.ToString());
    }
}
[VB.NET]
Sub GeocodeSingleAddressOnGeocodeServer()
    
    ' Open a GISServerConnection.
    Dim gisServerConnection As IGISServerConnection = New GISServerConnectionClass
    gisServerConnection.Connect("mendota")
    
    ' Get a GeocodeServer from the GISServerConnection.
    Dim serverObjectManager As IServerObjectManager = gisServerConnection.ServerObjectManager
    Dim serverContext As IServerContext = serverObjectManager.CreateServerContext("USA Streets", "GeocodeServer")
    Dim serverObject_GeocodeServer As IServerObject = serverContext.ServerObject
    Dim geocodeServer As IGeocodeServer = CType(serverObject_GeocodeServer, IGeocodeServer)
    
    ' Construct an address PropertySet to geocode.
    Dim object_PropertySet As Object = serverContext.CreateObject("esriSystem.PropertySet")
    Dim propertySet_Address As IPropertySet = CType(object_PropertySet, IPropertySet)
    With propertySet_Address
        .SetProperty("Street", "380 New York St.")
        .SetProperty("City", "Redlands")
        .SetProperty("State", "CA")
        .SetProperty("ZIP", "92373")
    End With
    
    ' Set the geocoding properties to use to geocode the address.
    Dim propertySet_Locator As IPropertySet = geocodeServer.GetLocatorProperties

    propertySet_Locator.SetProperty("MinimumMatchScore", "100")

        propertySet_Locator.SetProperty("SpellingSensitivity", "100")
            
            ' Geocode the address.
            Dim propertySet_Match As IPropertySet = geocodeServer.GeocodeAddress(propertySet_Address, propertySet_Locator)
            
            ' Print the match properties.
            Dim fields As IFields = geocodeServer.GetResultFields(Nothing)
            Dim int32_MatchFieldIndex As Int32
            Dim field As IField
            Dim point As IPoint
            
            For int32_MatchFieldIndex = 0 To fields.FieldCount - 1
                
                field = fields.Field(int32_MatchFieldIndex)
                Dim string_Name As String = field.Name
                Dim object_Match As Object = propertySet_Match.GetProperty(string_Name)
                
                If field.Type = esriFieldType.esriFieldTypeGeometry Then
                    
                    point = CType(object_Match, IPoint)
                    
                    If Not point.IsEmpty Then
                        
                        Debug.Print("X: " & point.X)
                        Debug.Print("Y: " & point.Y)
                        
                    End If
                    
                Else
                    
                    Debug.Print(field.AliasName & ": " & CStr(object_Match))
                    
                End If
                
            Next int32_MatchFieldIndex
            
        End Sub


See Also:

How to geocode a table of addresses
Location library overview
Sample: Find an address




To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
Engine Developer Kit Engine Runtime
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo