Ajax Autocomplete List Cities JSON-P API

Here is an example of how to add an Ajax Autocomplete Cities List to any website without generating any cross-site scripting errors, and without the need for any server side code or proxies. Fortunately there is not a lot that you need to know to get this running, but if you are interested in knowing how it works and why it does not raise site cross-scripting errors, then checkout the links below the following sample code. This script requires no server side code (php or otherwise) as it uses one of Geobytes’ free web services to get the list of cities. OK, first here is a demo:

Please enter your city here to see it work.


And here is the fully working example code sample (Please click on the link and it will dynamically insert the sample code inline here. It is hidden by default to save room – so that you can see the effect selecting a city above has on the Cities Details table below.).

Click here to open and close the code sample inline

Next, let’s take a look at how we use the selected city to fetch and display the city’s details via the (also totally free)….

Geobytes Get City Details JSON-P API


Once again, let’s start with a demo (Hint: Change the city in the above box to watch the city details change here.):

Country Code
Country

Region Code
Region
City Code
City
CityId
Fully Qualified
Name
Latitude
Longitude
Capital City
TimeZone
Nationality
Singular
Population
Nationality
Plural
CIA Map
Reference
Currency
Currency
Code

For a comprehensive description of each of the above fields please see the Understanding the Geo Tags & Geobytes Headers page.

Once again, click here to open and close the code sample inline
Country


Region
City
Fully Qualified
Name
Longitude
TimeZone
Population
CIA Map
Reference
Currency
Code

Country Code
Region Code City Code CityId Latitude Capital City Nationality
Singular
Nationality
Plural
Currency

If you need assistance implementing this, or if you have any suggestions or improvements then please feel free to post them in the page comments below.

Do I need an API Key?

Not if you are using it as it is intended to be used – and that is being accessed from the browser – where your requests will be spread over a large number of different IP Addresses. Alternatively, if you were calling it from a server, then our server would see a lot of requests originating from the same IP Address and would identify your server’s requests as a denial of service attack after about 4,000 requests in the same 60 minute period. I can’t see why any one would want to access this API from a server, but if you do you expect to be performing more than 4,000 requests per hour from the same IP Address, then you should consider becoming a $99 VIP Member to gain VIP access and appending your acount’s access token to your requests, or registering your site’s referral URL with us, so that your excess requests do not get blocked by our DOS mitigation system.

OK, So how does it work, and why doesn’t it raise site cross-scripting errors?

Well basically, it is because we pass back a function that defines an array containing the data for the autocomplete list rather then just the data itself. This then allows the returned object to be used with a <script> element, via a process known as “script element injection” .  There is a lot more to it then that, so rather than duplicate information from other sources, here are some links:

JSONP: http://en.wikipedia.org/wiki/JSONP

Same origin policy: http://en.wikipedia.org/wiki/Same_origin_policy

Why is the service free, and is it totally free – no ads, no links, nothing?

Yes it is totally free – no ads, no links, nothing.  You may have notice that we offer a number of free and mostly free services, and hopefully you also noticed that we also offer an even larger number of paid services – well the short answer is that we make our money out of our paid services, and gain recognition via our free services which helps us sell more paid services.  So we really don’t mind doing it, and besides we have been in this business for well over 10 years now (since 1999) and since the beginning we have always tried to give something back, and this philosophy has served us well.

How do you limit the search results to a country, state, or region?

Just add &filter=XX where XX is the country’s TLD such as US or UK etc., to the getJSON call.  So for example, if you wanted to only list cities within the United States then you would update the getJSON call to something like this:

Plus you can limit the autocomplete results even further by adding the state or region code as well – so for example you could limit the city list to cities within California by setting the filter parameter to USCA – which would look something like this:

You may notice that “USCA” is actually the Geobytes Location Code for California – try typing San Francisco into the above city text-box and then checking the “Region Code” in the City’s details table – this is a good way to findout the codes for other places – including those that are outside the US.

How to truncate off the state or country from a filtered list

If you do limit the results to a state or country, then you may wish to truncate off the state or country part of the response – to save it being repeated all of the time in the drop-down list. You can do this via the template parameter – which allows you to use “geobytes tags” to specify the format of the response.

For example, if you wanted to include only the city and state code in the response, then you could pass in a template like this.

Is the search limited to the first few letters or does it search the entire city name, including the country name?

By default it will only match on the start of the city name, however if you pass in fulltext=”true” then it will first search for an exact match on the prefix of the city name, and then search for a partial match any where within the full name of the city, including the country name.  

 

  • Nirav Patel

    Cities with a period, e.g. “St. Louis” don’t seem to work from the API. Is there a fix or a workaround for this?

  • CognitiveThinking

    ah yes – you’re right of course… doh!
    (Turns out that it is interpreting the dot as a part of an IP Address)
    I am working on a fix now – give it an hour or so, and it should be working.

  • Nirav Patel

    Amazing. Thanks!

  • Pingback: List of cities based on the country | 我爱源码网()

  • http://www.quicodomingo.com/ Quico Domingo

    Hi!

    I’m integrating your service in our registration form, but I see it only supports major cities, not villages.

    For example, in Spain, places like Balaguer, Tàrrega or Mollerussa are missing.

    Is there any way to enable it?

    Thanks!

  • http://www.geobytes.com Adrian

    Yes, if you have a list of villages that you would like added, then please feel free to email it through to me at adrian at geobytes.com and I will have them added.

  • Jim Cantor

    Hi, I think this tool will be very useful for me.

    I’ve a small problem: it is returning the same data twice. eg:

    http://gd.geobytes.com/AutoCompleteCity?callback=?&filter=AU&q=darwin

    returns:

    ?([“Darwin, NT, Australia”,”Darwin, NT, Australia”]);

    And it does not matter if I remove the filter: it still doubles up on the data.

  • http://www.geobytes.com Adrian

    ah yes – I see… I am on it…. will get back to you shortly…

  • CognitiveThinking

    Please see the “template” parameter above – I think that it is just what you are looking for.

  • http://www.geobytes.com Adrian

    ok – fixed.
    Please let me know if I can assist further.