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.

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.

Accuracy
City
Country
CountryCode
Latitude
Longitude
PostalCode
State
StateCode
Street

StateCode and CountryCode are always available on compound address fields, whether or not state and country picklists are enabled in your organization.

Note

The Address type extends the Location type, the data type used for compound geolocation fields.

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, BillingCity, BillingState, 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.

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 clean 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 the AppExchange.

Note

Object Reference for Salesforce and Force.com

Address Compound Fields

Retrieving Compound Address Fields

Retrieve a Standard Address Compound Field with the SOAP API

Using Compound Address Fields as Locations