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.

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

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 a geolocation field, and can be used as locations in SOQL WHERE and ORDER BY clauses. For example, here’s a SOQL query to retrieve the ten 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

The geolocation component of address fields isn’t set automatically. Set values for latitude and longitude on your addresses by using SOQL, Workbench, the SOAP or REST API, or a geocoding service. You can then use address fields as locatable values. Search the AppExchange for “geocode” to find some possible solutions.

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