Object Reference for Salesforce and Force.com

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

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

Geolocation Compound Fields

Geolocation fields are accessible in the SOAP and REST APIs as a Location, a structured compound data type, as well as individual latitude and longitude elements.
Using API 26.0 and later, geolocation fields are available in the SOAP and REST APIs as a compound field of type Location, a structured data type that 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.

  • Geolocation 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.
  • 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 before 26.0, as well as API 26.0 and above, use the individual latitude and longitude fields.
1SELECT location__latitude__s, location__longitude__s 
2FROM Warehouse__c

Returned Geolocation Data Types

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

In API versions below 30.0, SOAP calls return compound geolocation field values as strings, instead of a structured data type, for backwards compatibility. The string value format is:
1API location: [latitudeValue longitudeValue]
A regular expression to parse out the latitude and longitude values might look like 
1API location: \[([-+]?\d{1,2}([.]\d+)?) ([-+]?\d{1,3}([.]\d+)?)]
The first capture is the latitude, and the third is the longitude. You might need to cast the results to numbers, depending on how you plan to use it.