Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: VEGeocoder

require(["esri/virtualearth/VEGeocoder"], function(VEGeocoder) { /* code goes here */ });

Description

(Added at v1.4)
Bing Maps geocoder. See Locator for geocoding with ArcGIS Server locators. If you are working with the 1.x version of the ArcGIS JavaScript API, you will need to use token.

Note: there are restrictions when using Bing Maps geocoding:
  • Geocodes may not be stored for any purpose except caching for performance.
  • Geocodes may not be displayed on any map other than a Bing Map.
For more information on the Bing Maps terms of use when using Esri products, see the Microsoft Bing Maps Services Terms of Use.

Samples

Search for samples that use this class.

Constructors

NameSummary
new VEGeocoder(options)Creates a new VEGeocoder object.

Properties

NameTypeSummary
cultureStringSpecifies the culture in which to return results.

Methods

NameReturn typeSummary
addressToLocations(query, callback?, errback?)DeferredSends a geocode request to Bing Maps to find candidates for a single address specified in the query argument.
setCulture(culture)NoneSets the culture in which to return results.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
address-to-locations-complete
{
  geocodeResults: <VEGeocodeResult[]>
}
Fires when VEGeocode.addressToLocation() has completed.
error
{
  error: <Error>
}
Fires when an error occurs when executing the task.
Constructor Details

new VEGeocoder(options)

Creates a new VEGeocoder object.
Parameters:
<Object> options Required See options list for parameters.
options properties:
<String> bingMapsKey Optional Key used to access Bing Maps maps.
<String> culture Optional Specifies the culture in which to return results. The default value is "en-US". For a list of supported cultures, see http://msdn.microsoft.com/en-us/library/cc981048.aspx.
Sample:
require([
  "esri/virtualearth/VEGeocoder", ... 
], function(VEGeocoder, ... ) {
  var veGeocoder = new VEGeocoder({
    bingMapsKey: 'Enter Bing Maps Key Here'
  });
  ...
});
Property Details

<String> culture

Specifies the culture in which to return results. The default value is "en-US". For a list of supported cultures, see http://msdn.microsoft.com/en-us/library/cc981048.aspx.
Default value: en-US
See also: setCulture()
Method Details

addressToLocations(query, callback?, errback?)

Sends a geocode request to Bing Maps to find candidates for a single address specified in the query argument. On completion, the onAddressToLocationsComplete event is fired and the optional callback function is invoked.
Return type: Deferred
Parameters:
<String> query Required The address to locate.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onAddressToLocationsComplete event.
<Function> errback Optional An error object is returned if an error occurs during task execution.
Sample:

var query = "380 New York St, Redlands, CA, 92373";

veGeocoder.addressToLocations(query);

setCulture(culture)

Sets the culture in which to return results.
Parameters:
<String> culture Required The culture value. The default value is "en-US". For a list of supported cultures, see http://msdn.microsoft.com/en-us/library/cc981048.aspx.
See also: culture
Event Details
[ On Style Events | Connect Style Event ]

address-to-locations-complete

Fires when VEGeocode.addressToLocation() has completed. The result is an array of VEGeocodeResult. This is the same signature returned if the optional callback is specified. (Added at v3.6)
Event Object Properties:
<VEGeocodeResult[]> geocodeResults Contains an array of candidates that match the given address as well as their scores.
Sample:
require([
  "dojo/_base/connect", "esri/geometry/webMercatorUtils", "esri/symbols/SimpleMarkerSymbol",
  "esri/Color", "esri/graphic", ... 
], function(connect, webMercatorUtils, SimpleMarkerSymbol, Color, Graphic, ... ) {
  connect.connect(veGeocoder, "onAddressToLocationsComplete", function(geocodeResults) {
    var pointMeters = webMercatorUtils.geographicToWebMercator(geocodeResults[0].location);
    var pointSymbol = new SimpleMarkerSymbol().setSize(15).setColor(new Color("blue"));
    var locationGraphic = new Graphic(pointMeters,pointSymbol);
    map.graphics.add(locationGraphic);
  });
  ...
});

error

Fires when an error occurs when executing the task. (Added at v3.6)
Event Object Properties:
<Error> error Error message returned in a JavaScript error object.