esri.dijit.Geocoder/Esri World Locator - can't get sourceCountry to work

JoanneMcGraw

Hello,

Starting with the sample found at: https://developers.arcgis.com/en/javascript/jssamples/locator_simple.html and using the documentation at: https://developers.arcgis.com/en/javascript/jsapi/geocoder-amd.html, I have tried to figure out how to limit the results the Geocoder dijit returns to only those existing in Canada. I'm obviously having trouble understanding the documentation because I am unable to get this to work.

When I type "kingston" in the Geocoder dijit's field, the number one choice returned is in Jamaica not Ontario as I would expect (to be frank, I wouldn't expect to see an entry like Kingston, Jamaica at all in this but at a minimum I would expect the Canadian entries to have higher priority).

I have tried changing the instantiation of the geocoder variable in the sample as follows (among others but this seems the most likely given my understanding of what I'm reading):

geocoder = new Geocoder(     {         map: map         ,autoComplete: true         ,arcgisGeocoder: {             sourceCountry: "CAN" // I've tried "CA" in all my attempts too         }     }     ,"search" );

I don't actually want to not use the default World Locator service, I'm just trying to configure it. Am I supposed to fill in everything, including the URL or something? I wouldn't have thought so because if I add a placeholder parameter instead, that seems to work fine.

geocoder = new Geocoder(     {         map: map         ,autoComplete: true         ,arcgisGeocoder: {             placeholder: "blah"         }     }     ,"search" );

Can anyone provide any input regarding where I'm going wrong in this?

Cheers,
jtm

JoanneMcGraw

Well, when I didn't hear anything via the forums, I contacted ESRI support about this. Below is the incredibly-thorough and well-researched response (including attachments) I received. Unfortunately, while the suggested solution did deal with the autoComplete functionality returning values in Jamaica, its result did not provide the zooming functionality we preferred from the default arcgisGeocoder.

However, the method implemented in the " ModifiedSampleGeocodeDetailsWithSuggest.html" file (that is, editing the REST URL and including the sourceCountry there) gave me a further idea that, I believe, should be supported in future. Still using the default arcgisGeocoder, I added a 'suffix: " Canada"' parameter and this has limited the autocomplete results as desired; as well as giving us the zoom to result functionality we desired. (NOTE: The space before Canada is necessary because it is appending this string to whatever is in the Geocoder's input field.)

geocoder = new Geocoder(     {         map: map         ,autoComplete: true         ,arcgisGeocoder: {             sourceCountry: "CAN"              ,suffix: " Canada"         }     }     ,"search" );

Hoping this helps someone else,
jtm

The Esri World Geocoder used as default in the Geocoder dijit can be configured using the "arcgisGeocoder" parameter in the Geocoder constructor.
The optional configuration parameters listed in the documentation link you listed can be entered like this:

        geocoder = new Geocoder({
          map: map,
          arcgisGeocoder: {
            placeholder: "Search",
            sourceCountry: "CAN"
          }
        }, "search");

I've used two optional parameters here; "placeholder", and "sourceCountry".
Here's the full list of countries
http://resources.arcgis.com/en/help/arcgis-rest-api/#/Service_coverage/02r300000018000000/

The "Single input field geocoding" is the REST endpoint being used to generate results. Here's all the information on it http://resources.arcgis.com/en/help/arcgis-rest-api/#/Single_input_field_geocoding/02r300000015000000/
You can see that sourceCountry has these Acceptable values:
- Full country name
- ISO 3166-1 2-digit country code
- ISO 3166-1 3-digit country code.
I recommend using the 3-digits country code, it's easy to write and read.

The sourceCountry parameter doesn't have an effect when suggesting results for auto-compelete but it's working fine when zooming to the first result.
You can see in the article "Working with suggestions" that the sourceCountry is not one of the input parameters http://resources.arcgis.com/en/help/arcgis-rest-api/#/Working_with_suggestions/02r300000238000000/
So, even if the geocoder dijit sends the sourceCountry as one of the parameters, it won't have an effect.

See the attached HTML file named "ModifiedSample.html" for a working sample that zooms "kingston" to "Kingston, ON" and not "Jamaica" even though the first suggestion is there.
You can use the JavaScript API Sandbox to quickly test this modified sample http://developers.arcgis.com/en/javascript/sandbox/sandbox.html

There's another helpful sample that allows you build your own geocoder dijit; Geocoder with custom service https://developers.arcgis.com/en/javascript/jssamples/locator_service.html
This sample shows how to replace the Esri World Geocoder with another service.
However, you can use this sample with the Esri World Geocoder, but in a way that can allow you a little bit more control.

When configuring the custom geocoder you need to provide 3 parameters; URL, Name, and singleLineFieldName.

The URL to the Esri World Geocoder service is http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer

Name is a custom name to refer to this geocoder (you can use multiple geocoders, that's why the name is needed).

singleLineFieldName is the name of the parameter sent to the server.
The singleLineFieldName for the Esri World Geocoder service is "SingleLine"

See the attached file "ModifiedSampleGeocodeDetailsWithSuggest.html" for a modified sample that calls the Esri World Geocoder but using a custom geocoder as in the sample listed above.

This way doesn't let me specify the sourceCountry as the first modified sample does.
However, I found that if I modified the URL to include the parameter "sourceCountry=CAN", this limits the search suggestions (autocomplete) and results to Canada.
Note: This is something that is not in the documentation, and it's something that I found. It's supported by Esri and could change in upcoming releases.

To sum up: The "ModifiedSample.html" shows how to use the geocoder dijit to limit results to Canada but it doesn't limit the autocomplete suggestions.
The "ModifiedSampleGeocodeDetailsWithSuggest.html" is a possible workaround that limits the results and autocomplete suggestions to Canada.

ESRISupportHTMLs.zip