Address Compound Fields

Standard addresses—addresses built into standard objects in Salesforce—are accessible in the SOAP and REST APIs as an Address, a structured compound data type, as well as individual address elements. If you enabled Custom Address Fields, you can also add custom fields that mimic the standard address field behavior.

The Address type extends the Location type, the data type used for compound geolocation fields. Using API 30.0 and later, standard addresses are available in the SOAP and REST APIs as a compound field of type Address, a structured data type that combines the following fields.

Field	Type	Description
Accuracy	picklist	Accuracy level of the geocode for the address. For example, this field is known as MailingGeocodeAccuracy on Contact.
City	string	The city detail for the address. For example, this field is known as MailingCity on Contact.
Country	string	The country detail for the address. For example, this field is known as MailingCountry on Contact.
CountryCode	picklist	The ISO country code for the address. For example, this field is known as MailingCountryCode on Contact. CountryCode is always available on compound address fields, whether or not state and country/territory picklists are enabled in your organization.
Latitude	double	Used with Longitude to specify the precise geolocation of the address. For example, this field is known as MailingLatitude on Contact.
Longitude	double	Used with Latitude to specify the precise geolocation of the address. For example, this field is known as MailingLongitude on Contact.
PostalCode	string	The postal code for the address. For example, this field is known as MailingPostalCode on Contact.
State	string	The state detail for the address. For example, this field is known as MailingState on Contact.
StateCode	picklist	The ISO state code for the address. For example, this field is known as MailingStateCode on Contact. StateCode is always available on compound address fields, whether or not state and country/territory picklists are enabled in your organization.
Street	textarea	The street detail for the address. For example, this field is known as MailingStreet on Contact.

Address fields are provided on many standard objects, such as Account, Contact, Quote, and User. Some objects provide fields for multiple addresses. For example, Account provides for four different addresses. In this case, address field names are prefixed with the type of address, for example, BillingAddress, ShippingAddress, and so on.

Standard address compound fields are read-only, and are only accessible using the SOAP and REST APIs. See Compound Field Considerations and Limitations for additional details of the restrictions this imposes.

Note

When an address is geocoded, its latitude and longitude fields are populated with coordinates. A related geolocation field is also populated. Typically, geocoding service providers geocode addresses, and rate the accuracy of the geocodes.

The accuracy subfield GeocodeAccuracy stores the accuracy data for a geocoded location. External geolocation apps can get the accuracy level of a geocoded address via the API. When you retrieve an address via the API, any accuracy data is included. You can also retrieve the accuracy information by itself, if needed.

Like its parent, the compound Address field, the GeocodeAccuracy field is only available for standard address fields on standard objects.

Custom Address Fields

If you enabled Custom Address Fields, the Address field type is available in Object Manager when you add a custom field. Custom address fields mimic the behavior or standard address fields with some limitations.

For more information see the Custom Address Fields Developer Guide.

Retrieving Compound Address Fields

Using compound fields can simplify code that works with addresses, especially for SOQL queries. SOQL SELECT clauses can reference addresses directly, instead of all of the individual component fields.

1SELECT Name, BillingAddress
2FROM Account

To write code that’s compatible with API versions before 30.0, as well as API 30.0 and above, use the individual fields:

1SELECT Name, BillingStreet, BillingCity, BillingState, BillingPostalCode,
2       BillingCountry, BillingLatitude, BillingLongitude
3FROM Account

Compound address field values are returned as a structured data type, Address. Code that works with compound address fields needs to reference the individual components of the returned value. See the code sample below.

Retrieve a Standard Address Compound Field with the SOAP API

The following Java method uses the Salesforce SOAP API to retrieve and display the Mailing Address for a list of contacts.

1// Modified version of code in the SOAP API QuickStart
2private void querySample() {
3    String soqlQuery = "SELECT FirstName, LastName, MailingAddress FROM Contact";
4    try {
5        QueryResult qr = connection.query(soqlQuery);
6        boolean done = false;
7
8        if (qr.getSize() > 0) {
9            System.out.println("\nLogged-in user can see "
10              + qr.getRecords().length + " contact records.");
11
12            while (!done) {
13                System.out.println("");
14                SObject[] records = qr.getRecords();
15                for (int i = 0; i < records.length; ++i) {
16                    Contact con = (Contact) records[i];
17                    String fName = con.getFirstName();
18                    String lName = con.getLastName();
19
20                    // Access the compound address field MailingAddress
21                    Address addr = (Address) con.getMailingAddress();
22                    String streetAddr = "";
23                    if (null != addr) streetAddr = addr.getStreet();
24
25                    if (fName == null) {
26                        System.out.println("Contact " + (i + 1) + ": " + lName +
27                            " -- " + streetAddr);
28                    } else {
29                        System.out.println("Contact " + (i + 1) + ": " + fName +
30                            " " + lName +
31                            " -- " + streetAddr);
32                    }
33                }
34
35                if (qr.isDone()) {
36                    done = true;
37                } else {
38                    qr = connection.queryMore(qr.getQueryLocator());
39                }
40            }
41        } else {
42            System.out.println("No records found.");
43        }
44    } catch (ConnectionException ce) {
45        ce.printStackTrace();
46    }
47}

Using Compound Address Fields as Locations

Compound address fields include latitude and longitude fields. Address fields can be used as locations in SOQL WHERE and ORDER BY clauses. For example, here’s a SOQL query that uses the GEOLOCATION function to retrieve the 10 accounts closest to San Francisco.

1SELECT Id, Name, BillingAddress
2FROM Account
3WHERE DISTANCE(BillingAddress, GEOLOCATION(37.775,-122.418), 'mi') < 20 
4ORDER BY DISTANCE(BillingAddress, GEOLOCATION(37.775,-122.418), 'mi')
5LIMIT 10

In Developer, Professional, Enterprise, Unlimited, and Performance editions, Salesforce can automatically add or update geolocation fields for Account, Contact, Lead, and WorkOrder records. To use this feature, your administrator must enable the geo data integration rule for each object. For all other objects and editions, set values for latitude and longitude by using SOQL, Workbench, SOAP or REST API, or a geocoding service. You can then use address fields as locatable values. To find geocoding services, search AppExchange.