Object Reference for Salesforce and Force.com

Object Basics
Primitive Data Types
Field Types
Compound Fields
Address Compound Fields
Geolocation Compound Field
Compound Field Considerations and Limitations
API Data Types and Salesforce Field Types
Required Fields
System Fields
API Field Properties
Custom Fields
Custom Objects
External Objects
Relationships Among Objects
Factors that Affect Data Access
Reference
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Geolocation Compound Field

Geolocation fields are accessible in the SOAP and REST APIs as a Location—a structured compound data type—or as individual latitude and longitude elements.
In API versions 26.0 and later, geolocation fields are available in the SOAP and REST APIs as a compound field of type Location. This structured data type contains the following fields.
  • latitude
  • longitude

SOAP calls that use API versions earlier than 30.0 return geolocation compound values as strings. See “Returned Geolocation Data Types” later in this topic.

Note

Geolocation fields are provided on many standard objects, such as Account, Contact, Quote, and User, as part of their address field or fields. Geolocation fields can also be added as custom fields to standard or custom objects.

  • A geolocation compound field is read-only, although its latitude and longitude subfields are editable. You can only access compound fields using the SOAP or REST API. For more information about working with compound fields and their subfields, see Compound Field Considerations and Limitations.
  • Although geolocation fields appear as a single field in the user interface, custom geolocation fields count as three custom fields towards your organization’s limits: one for latitude, one for longitude, and one for internal use.

Note

Retrieving Compound Geolocation Fields

Using compound fields can simplify code that works with geolocations, especially for SOQL queries. SOQL SELECT clauses can reference geolocations directly, instead of the individual component fields.
1SELECT location__c 
2FROM Warehouse__c
To write code that’s compatible with API versions earlier than 26.0 and with API versions 26.0 and later, use the individual latitude and longitude fields.
1SELECT location__latitude__s, location__longitude__s 
2FROM Warehouse__c

Returned Geolocation Data Types

A compound geolocation field value is returned as the structured data type Location. Code that works with compound geolocation fields must reference the individual components of the returned value. See the sample code in Address Compound Fields.

In API versions earlier than 30.0, SOAP calls return compound geolocation field values as strings, instead of as a structured data type, for backward compatibility. If you plan to display your latitude and longitude values or pass them to a service that expects strings, use the values that are returned. If you plan to use the values in mathematical calculations or pass them to a map service that expects numbers, cast the results to numbers.

The string value format is:
1API location: [latitudeValue longitudeValue]
An example of a regular expression to parse out the latitude and longitude values is: 
1API location: \[([-+]?\d{1,2}([.]\d+)?) ([-+]?\d{1,3}([.]\d+)?)]
The first capture is the latitude, and the third is the longitude.