The GetHostedData() Apex method retrieves geographical IDs for properties and displays them in Salesforce Maps. We accomplish this retrieval in two requests while using the same method. The first request returns geographical IDs for properties that Salesforce Maps hosts for a specified area and filter criteria. The second request takes these geographical IDs and display parameters, such as legend and popup information, and displays them in Salesforce Maps.
Salesforce Maps works with data providers that supply property and business data. Periodically, these providers update their data, which can affect custom code. If the providers change their data formats, update your custom code accordingly. Salesforce Maps can update, replace, or remove property data at any time.
Signature
Map<String, Object> maps.API.GetHostedData(String parameters)
Where,
- maps is the namespace that’s available after you install Salesforce Maps.
- API is the class that contains the global methods exposed to developers.
- GetHostedData() is the method.
Example code to fetch geographic identifiers.
The initial example request made with the GetHostedData() method retrieves geographic identifiers for women-owned businesses hosted by Salesforce Maps. These businesses generate revenue in the range of $100,000 to $1,000,000 within a designated geographical area.
Warning
If you invoke methods within a flow, process builder, or trigger, do one of the following to avoid uncommitted work errors.
- Call the methods through a future method
- Call the methods as queueable
Different processes refresh the token, such as plotting a route or schedule. The refresh process is almost immediate after each qualifying action occurs.
Parameter Input Format
{
"mapinfo": { // Boundary area.
"offset": integer, // Pagination when the number of results is large.
"limit": integer, // Maximum number of geographical IDs to return in response.
"celng": decimal, // Longitude coordinate to search closest records.
"celat": decimal, // Latitude coordinate to search closest records.
"swlng": decimal, // South-Western longitude coordinate for map boundary.
"swlat": decimal, // South-Western latitude coordinate for map boundary.
"nelng": decimal, // North-Eastern longitude coordinate for map boundary.
"nelat": decimal // North-Eastern latitude coordinate for map boundary.
},
"data": {
"filters": [{}], // Filters to limit the results.
"defaultMarkerColor": "String:String", // Hex color : Type of marker to be returned
"level_id": "String", // Sub-section of the data specified by file_id.
"file_id": "String" // Data being queried, for example, business, property, political boundaries, etc.
}
}
Illustration
// Create the boundary area.
Map<String,Decimal> mapInfo = new Map<String,Decimal>{
'nelat' => 49.92293,
'nelng' => -55.72265,
'swlat' => 29.49698,
'swlng' => -140.00976,
'celat' => 40.48038,
'celng' => -97.86621,
'limit' => 6,
'offset' => 0
};
// Create the filters.
Map<String,Object> femaleOwned = new Map<String,Object>{
'topic_id' => 'female_owned',
'operator' => 'equals',
'values' => new List<String>{'Yes'}
};
Map<String,Object> locationSalesTotal = new Map<String,Object>{
'topic_id' => 'location_sales_total',
'operator' => 'range',
'min' => '100000',
'max' => '1000000'
};
List<Map<String,Object>> filters = new List<Map<String,Object>>();
filters.add(femaleOwned);
filters.add(locationSalesTotal);
// Add the filters and additional 'data' parameters.
Map<String,Object> dataMap = new Map<String,Object>{
'filters' => filters,
'defaultMarkerColor' => '93c47d:Circle',
'level_id' => '42',
'file_id' => 'business'
};
// Build the request.
Map<String,Object> request = new Map<String,Object>();
request.put('data', dataMap);
request.put('mapinfo', mapInfo);
String requestString = JSON.serialize(request);
// Call the GetHostedData() method with the boundary area and filter criteria.
Map<String, Object> response = maps.API.GetHostedData(requestString);
// Log the resulting locations.
System.debug(JSON.serialize(response));
Exemplary Response Containing Geographic Identifiers
Although the return value is an Apex Map<String, Object> object, this JSON response illustrates the essential data you receive in the resulting map.
{
"endPoint":"https://internal.na.sfmapsapi.com/data/markers/2",
"limitInfo":{
"QueryRows":"12 / 50000",
"Queries":"8 / 100",
"HeapSize":"70683 / 6000000",
"CPUTime":"171 / 10000"
},
"request":"{\"mapinfo\":{\"offset\":0,\"limit\":6,\"celng\":-97.86621,\"celat\":40.48038,\"swlng\":-140.00976,\"swlat\":29.49698,\"nelng\":-55.72265,\"nelat\":49.92293},\"data\":{\"filters\":[{\"values\":[\"Yes\"],\"operator\":\"equals\",\"topic_id\":\"female_owned\"},{\"max\":\"1000000\",\"min\":\"100000\",\"operator\":\"range\",\"topic_id\":\"location_sales_total\"}],\"defaultMarkerColor\":\"93c47d:Circle\",\"level_id\":\"42\",\"file_id\":\"business\"}}",
"params":{
"data":{
"file_id":"business",
"level_id":"42",
"defaultMarkerColor":"93c47d:Circle",
"filters":[
{
"topic_id":"female_owned",
"operator":"equals",
"values":[
"Yes"
]
},
{
"topic_id":"location_sales_total",
"operator":"range",
"min":"100000",
"max":"1000000"
}
]
},
"mapinfo":{
"nelat":49.92293,
"nelng":-55.72265,
"swlat":29.49698,
"swlng":-140.00976,
"celat":40.48038,
"celng":-97.86621,
"limit":6,
"offset":0
}
},
"success":true,
"data":{ // List of geographical IDs.
"ids":[
"11140017125231",
"11140017127280",
"11140017102994",
"11140017127285",
"11132553548894",
"11140017127286"
]
}
}
Example code for showcasing geographic identifiers.
The second request using the GetHostedData() method takes the geographical IDs and display parameters, such as legend and popup information, and displays them in Salesforce Maps.
Parameter Input Format
{
"mapinfo": {
"offset": integer, // Pagination when the number of results is large.
"limit": integer, // Maximum number of geographical IDs to return in response.
"celng": decimal, // Longitude coordinate to search closest records.
"celat": decimal, // Latitude coordinate to search closest records.
"swlng": decimal, // South-Western longitude coordinate for map boundary.
"swlat": decimal, // South-Western latitude coordinate for map boundary.
"nelng": decimal, // North-Eastern longitude coordinate for map boundary.
"nelat": decimal // North-Eastern latitude coordinate for map boundary.
},
"data": {
"popup": { // Popup information for the displayed locations.
"tabs": [{}],// Array of tab objects to be displayed in the popup.
"header": [{}] // Array of objects containing information of the tab headers.
},
"legend": { // Map legend.
"rows": [{}], // Array of objects containing information of each row in the legend.
"subTitle": "String", // Subtitle of the legend.
"title": "String" // Title of the the legend.
},
"defaultMarkerColor": "String:String", // Hex color : Type of marker to be returned.
"level_id": "String", // Sub-section of the data specified by file_id.
"file_id": "String" // Data being queried, for example, business, property, political boundaries, etc.
},
"aggregates": Boolean, // Aggregated data of all the records returned. It contains the min, max, sum, and averages of the records.
"details": Boolean, // Return the details for the requested records.
"ids": [] // Array of geographical IDs.
}
Illustration
// Create the map legend.
Map<String,Object> row1 = new Map<String,Object>
{
'topic_id' => 'female_owned',
'operator' => 'equals',
'values' => new List<String>{'Yes'},
'color' => '38d84a:Marker'
};
Map<String,Object> row2 = new Map<String,Object>
{
'topic_id' => 'location_sales_total',
'operator' => 'range',
'min' => '10',
'max' => '1000000',
'color' => '38d87c:Marker'
};
List<Map<String,Object>> legendRows = new List<Map<String,Object>>();
legendRows.add(row1);
legendRows.add(row2);
Map<String,Object> legend = new Map<String,Object>{
'title' => 'Total Company Sales',
'subTitle' => 'Breakdown of businesses based on company sales',
'rows' => legendRows
};
// Create the popup header.
List<Map<String,String>> header = new List<Map<String,String>>();
header.add(new map<String,String>{
'file_id' => 'business',
'topic_id' => 'location_sales_total'
}
);
// Create the popup tabs.
List<Map<String,String>> tabData = new List<Map<String,String>>();
tabData.add(new map<String,String>{'file_id' => 'business', 'topic_id' => 'location_sales_total'});
Map<String,Object> tab = new map<String,Object>{
'tab_id' => '1520003558209',
'tab_label' => 'Additional info',
'data' => tabData
};
List<Map<String,Object>> tabs = new List<Map<String,Object>>();
tabs.add(tab);
// Build the popup object.
Map<String,Object> popup = new Map<String,Object>{
'header' => header,
'tabs' => tabs
};
// Build the 'data' object.
Map<String,Object> data = new Map<String,Object>{
'file_id' => 'business',
'level_id' => '42',
'defaultMarkerColor' => '93c47d:Circle',
'legend' => legend,
'popup' => popup
};
// Create the boundary area.
Map<String,Decimal> mapInfo = new Map<String,Decimal>{
'nelat' => 49.92293,
'nelng' => -55.72265,
'swlat' => 29.49698,
'swlng' => -140.00976,
'celat' => 40.48038,
'celng' => -97.86621,
'limit' => 6,
'offset' => 0
};
// Create the array of geographical IDs.
List<String> returnedIds = new List<String>{'11140017125231','11140017127280','11140017102994','11140017127285','11132553548894','11140017127286'};
// Build the request.
Map<String,Object> request = new Map<String,Object>{
'ids' => returnedIds,
'details' => true, // Return the details of the requested records.
'aggregates' => true, // Get the aggregated record data.
'data' => data,
'mapinfo' => mapInfo
};
String requestString = JSON.serialize(request);
// Call the GetHostedData() method with the geographical IDs and display parameters.
Map<String, Object> response = maps.API.GetHostedData(requestString);
//Log the results.
System.debug(JSON.serialize(response));
Exemplary Response for Displaying Geographic Identifiers
Although the return value is an Apex Map<String, Object> object, this JSON response illustrates the essential data you receive in the resulting map.
{
"endPoint": "https://internal.na.sfmapsapi.com/data/markers/2",
"limitInfo": {
"QueryRows": "12 / 50000",
"Queries": "8 / 100",
"HeapSize": "79714 / 6000000",
"CPUTime": "129 / 10000"
},
"request": "{\"mapinfo\":{\"offset\":0,\"limit\":6,\"celng\":-97.86621,\"celat\":40.48038,\"swlng\":-140.00976,\"swlat\":29.49698,\"nelng\":-55.72265,\"nelat\":49.92293},\"data\":{\"popup\":{\"tabs\":[{\"data\":[{\"topic_id\":\"location_sales_total\",\"file_id\":\"business\"}],\"tab_label\":\"Additional info\",\"tab_id\":\"1520003558209\"}],\"header\":[{\"topic_id\":\"location_sales_total\",\"file_id\":\"business\"}]},\"legend\":{\"rows\":[{\"color\":\"38d84a:Marker\",\"values\":[\"Yes\"],\"operator\":\"equals\",\"topic_id\":\"female_owned\"},{\"color\":\"38d87c:Marker\",\"max\":\"1000000\",\"min\":\"10\",\"operator\":\"range\",\"topic_id\":\"location_sales_total\"}],\"subTitle\":\"Breakdown of businesses based on company sales\",\"title\":\"Total Company Sales\"},\"defaultMarkerColor\":\"93c47d:Circle\",\"level_id\":\"42\",\"file_id\":\"business\"},\"aggregates\":true,\"details\":true,\"ids\":[\"11140017125231\",\"11140017127280\",\"11140017102994\",\"11140017127285\",\"11132553548894\",\"11140017127286\"]}",
"params": {
"ids": [
"11140017125231",
"11140017127280",
"11140017102994",
"11140017127285",
"11132553548894",
"11140017127286"
],
"details": true,
"aggregates": true,
"data": {
"file_id": "business",
"level_id": "42",
"defaultMarkerColor": "93c47d:Circle",
"legend": {
"title": "Total Company Sales",
"subTitle": "Breakdown of businesses based on company sales",
"rows": [
{
"topic_id": "female_owned",
"operator": "equals",
"values": [
"Yes"
],
"color": "38d84a:Marker"
},
{
"topic_id": "location_sales_total",
"operator": "range",
"min": "10",
"max": "1000000",
"color": "38d87c:Marker"
}
]
},
"popup": {
"header": [
{
"file_id": "business",
"topic_id": "location_sales_total"
}
],
"tabs": [
{
"tab_id": "1520003558209",
"tab_label": "Additional info",
"data": [
{
"file_id": "business",
"topic_id": "location_sales_total"
}
]
}
]
}
},
"mapinfo": {
"nelat": 49.92293,
"nelng": -55.72265,
"swlat": 29.49698,
"swlng": -140.00976,
"celat": 40.48038,
"celng": -97.86621,
"limit": 6,
"offset": 0
}
},
"success": true,
"data": {
"aggregates": [
{
"avg": 329333.3333333333,
"sum": 1976000,
"max": 461000,
"min": 303000,
"label": "Sales: Total (USD)"
}
],
"legend": {
"rows": [
{
"values": [
"Yes"
],
"row_id": "row-0",
"operator": "equals",
"color": "38d84a:Marker",
"topic_id": "female_owned"
},
{
"max": "1000000",
"min": "10",
"row_id": "row-1",
"operator": "range",
"color": "38d87c:Marker",
"topic_id": "location_sales_total"
},
{
"values": [
"--Other--"
],
"row_id": "row-other",
"operator": "equals",
"color": "93c47d:Circle",
"topic_id": "female_owned"
}
],
"subTitle": "Breakdown of businesses based on company sales",
"title": "Total Company Sales"
},
"markers": [
{
"popup": {
"tabs": [
{
"data": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
],
"tab_id": "1520003558209",
"tab_label": "Additional info"
}
],
"header": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
]
},
"position": {
"lng": "-97.886011",
"lat": "40.441185"
},
"color": "38d84a:Marker",
"rowid": "row-0",
"datatype": "business",
"c2c": true,
"uid": "11140017125231",
"geoid": "11140017125231",
"label": "Urbauer Family Farm"
},
{
"popup": {
"tabs": [
{
"data": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
],
"tab_id": "1520003558209",
"tab_label": "Additional info"
}
],
"header": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
]
},
"position": {
"lng": "-97.800868",
"lat": "40.466693"
},
"color": "38d84a:Marker",
"rowid": "row-0",
"datatype": "business",
"c2c": true,
"uid": "11140017102994",
"geoid": "11140017102994",
"label": "Rauscher Family Farm"
},
{
"popup": {
"tabs": [
{
"data": [
{
"formatted_value": "$461,000.00",
"value": "461000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
],
"tab_id": "1520003558209",
"tab_label": "Additional info"
}
],
"header": [
{
"formatted_value": "$461,000.00",
"value": "461000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
]
},
"position": {
"lng": "-97.850325",
"lat": "40.408435"
},
"color": "38d84a:Marker",
"rowid": "row-0",
"datatype": "business",
"c2c": true,
"uid": "11132553548894",
"geoid": "11132553548894",
"label": "Johnson Insurance & Financial Services"
},
{
"popup": {
"tabs": [
{
"data": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
],
"tab_id": "1520003558209",
"tab_label": "Additional info"
}
],
"header": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
]
},
"position": {
"lng": "-97.861957",
"lat": "40.549917"
},
"color": "38d84a:Marker",
"rowid": "row-0",
"datatype": "business",
"c2c": true,
"uid": "11140017127285",
"geoid": "11140017127285",
"label": "Schmer Family Farm"
},
{
"popup": {
"tabs": [
{
"data": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
],
"tab_id": "1520003558209",
"tab_label": "Additional info"
}
],
"header": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
]
},
"position": {
"lng": "-97.863180",
"lat": "40.557545"
},
"color": "38d84a:Marker",
"rowid": "row-0",
"datatype": "business",
"c2c": true,
"uid": "11140017127286",
"geoid": "11140017127286",
"label": "Leininger Family Farm"
},
{
"popup": {
"tabs": [
{
"data": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
],
"tab_id": "1520003558209",
"tab_label": "Additional info"
}
],
"header": [
{
"formatted_value": "$303,000.00",
"value": "303000",
"topic_id": "location_sales_total",
"label": "Sales: Total (USD)"
}
]
},
"position": {
"lng": "-97.900864",
"lat": "40.509699"
},
"color": "38d84a:Marker",
"rowid": "row-0",
"datatype": "business",
"c2c": true,
"uid": "11140017127280",
"geoid": "11140017127280",
"label": "Cloet Family Farm"
}
]
}
}