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

Region Code
City Code
Fully Qualified
Capital City

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

Fully Qualified

Country Code
Region Code City Code CityId Latitude Capital City Nationality

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 expect to be performing more than 4,000 requests per hour from the same IP Address, then you should consider becoming a $9.99 VIP Member to gain VIP access and appending your account’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,YY,ZZ where XX,YY,ZZ is a comma delimited list of the countries TLDs that you wish to limit your result to.  So for example, if you wanted to only list cities within the United States and Canada, 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 find out 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.

Can the larger cities be sorted to the top?

Yes, by default the Autocomplete list is sorted by the fully qualified city name, but if you prefer that it be sorted by the size of the city then you pass in sort=size which will cause the larger cities within the list to be sorted to the top.

For example:


  • 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 | 我爱源码网()

  • 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?


  • 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:



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

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

  • 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.

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

  • Brendan White

    The problem with the first one is that the city in Australia is Sydney with a Y, not Sidney with an I. This URL works:


  • Brendan White

    …and when I go to http://gd.geobytes.com/AutoCompleteCity?callback=example&filter=US&q=Wellington it brings up a bunch of results. Perhaps someone has fixed it?

  • Bob Pawlowski

    Someone did fix the Wellington call and the Sydney call was a mis-spelling.

  • shivani

    Can any one please tell how many languages this api support and how to add language parameter to the api.

  • CognitiveThinking

    At the moment the API does not offer language support, but we are looking at it. So if you are happy to share your thoughts on how you would expect this to work, and perhaps some detail of your specific requirements, then I’ll make sure that this is consider in the design of the facility. For example, in addition to support for other languages, I was also looking at including support for alternative place names, and common miss-spelling. Is there anything in particular that you had in mind?

    In any case, please let me know if I can assist further.

  • Ran Smith

    This tool doesn’t seem to be working (for the last 15 hours or so). Any status update on when it will come back online?

  • CognitiveThinking

    Doh! – (It was working for me.)
    It is back now – very sorry to those that were affected.

  • Ran Smith

    Thank you very much! It’s an awesome tool!

  • dhruv

    how it is possoble for console application

  • CognitiveThinking

    I am not sure what you mean, but if you wish to fetch the cities details from the command line, then you would use something like this:
    curl -s http://getcitydetails.geobytes.com/GetCityDetails?fqcn=Chicago,%20IL,%20United%20States | grep -oP ‘(?<=”geobytesfqcn”:”)[^”]*’

  • dhruv

    please give me support for console application

  • Vinod Konda

    The code is not bringing updated cities/state name… for e.g. hyderabad in India is part of TN state now, previously AP. Please check

  • I am keen to help, but I need more specific information regarding your requirements.

  • CognitiveThinking

    Thanks for the heads-up…

    With regards to Hyderabad, I am not sure when to update our records to reflect the change, as according to https://en.wikipedia.org/wiki/Hyderabad the city does not cease being the capital of Andhra until 2024.

    Here is a quote from that page:
    According to the Andhra Pradesh Reorganisation Act, 2014 part 2 Section 5:[57] “(1) On and from the appointed day, Hyderabad in the existing State of Andhra Pradesh, shall be the common capital of the State of Telangana and the State of Andhra Pradesh for such period not exceeding ten years. (2) After expiry of the period referred to in sub-section (1), Hyderabad shall be the capital of the State of Telangana and there shall be a new capital for the State of Andhra Pradesh.”

    In the interim, I am thinking of creating a new city in our database for Hyderabad the capital of the State of Telangana. What would you recommend?

  • Vinod Konda

    Thanks CognitiveThinking for quick reply, first of all i should appreciate the work you have done and your knowledge of research before implementing.
    There are list of other cities that are part of the new state Telangana which is bifurcated from AP, here is the list https://en.wikipedia.org/wiki/List_of_cities_in_Telangana_by_population
    and i think hyderabad needs to be added as a city for both states…

    U ROCK

  • CognitiveThinking

    Cool – that helps a lot – I will added the cities in that list to the new State of Telangana as duplicates for now. The changes should be visible from our web site on Monday night.
    Thanks again for bring this to my attention, and for your assistance – I very much appreciate it.
    (BTW You’re too kind 🙂 – but I do appreciate your encouragement.)

  • Vinod Konda

    Thanks Looking forward for it

  • CognitiveThinking

    Done. Hyderabad and the other 10 cities listed on https://en.wikipedia.org/wiki/List_of_cities_in_Telangana_by_population have now be added/updated in our database, and should now be visible from our web site and APIs.
    Thanks again for your help with this.

  • no_play

    in chrome this doesn’t work ?
    XMLHttpRequest cannot load http://gd.geobytes.com/AutoCompleteCity?callback=cities&q=fra. No ‘Access-Control-Allow-Origin’ header is present on the requested resource.

  • CognitiveThinking

    Yes, it returns a JSON, or JSON-P depending whether you pass in a callback parameter, so rather than using XMLHttpRequest, I would suggest something like this, but if you have a better approach then please let me know.

  • Sam112

    How do I submit request to add Cities that are missing. We are using this API for location search in the app we are developing. However many cities are missing. Anyway we can send you request to add these cities? Or add it ourselves?

  • CognitiveThinking

    Yes, I would be more than happy to add any cities that you find that are missing from our database. Please feel free to email them through to me at adrian@geobytes.com
    Thank you – I appreciate it.

  • Barron

    Interesting, is it possible to host this on my own server ?

  • Tejas Bhatt

    Hi, can i save data into my database ? my usecase is I let users search for cities and then add that city to their profile
    I want to know if i can save the city id to my database and when the users logs in next time they should be able to see the cities that they have added to their account.
    I don’t mind paying for the premium version if it is needed.
    Please let me know

    Also if you don’t mind can you please explain how is your service different from Google Maps Places Autocomplete we can also get a list of cities from that.

  • CognitiveThinking

    Yes, sure. You can record the city details in your database and access them directly later. In fact you can download all of the cities data here: http://www.geobytes.com/lamp-solution/
    With regards to Google Maps Places Autocomplete – I am not all that familiar with it, but I thought that their terms of use were much more restrictive, and that it was much more complicated to use, and beside, we give you virtually unlimited look ups (4096 per IP Address) and they limit you to 150,000 accesses per day.

  • CognitiveThinking
  • Barron

    OK, but does this still read the info from your server ?

  • CognitiveThinking

    No, you would now need to update your application to read it from your own server, and of accordingly update your server to provide the information.

  • CognitiveThinking
  • Barron

    I see. OK well the application is in development and now would be the time to build around it.

  • Barron

    Question CT,

    Is this information available on CSV ?


  • Marco

    I have purchased the VIP access because I’m calling the autocompletecity functionality from a https webpage. From what I understand, this enables me to do so without getting the “Show All Content” warning on IE. However, I’m still getting it even when referencing my key in the URL when using my ajax call.

    Below is the code. Obviously, the ****** represends my real VIP key. Any ideas?

    function autoCompleteCity(ele) {
    /* This function auto-completes any US city the user types into
    the an input field.

    Parameter: ele
    This is the jQuery object of the input city field */

    source: function( request, response ) {
    url: “https://gd.geobytes.com/AutoCompleteCity?callback=?&key=***********************&filter=US&template=,%20”,
    dataType: “jsonp”,
    data: {
    q: request.term
    success: function( data ) {
    response( data );
    minLength: 3,
    select: function( event, ui ) {
    ele.val( ui.item ? ui.item.label : “”);
    open: function() {
    $( this ).removeClass( “ui-corner-all” ).addClass( “ui-corner-top” );

    // if user did not select an option, reset elem’s value to “”
    close: function() {
    if(ele.val().indexOf(“,”) < 0)
    $( this ).removeClass( "ui-corner-top" ).addClass( "ui-corner-all" );

  • Barron

    Hello again. I was referring to the city list. I there a JSON or CSV with the data to download ? Thanks..

  • CognitiveThinking

    Hi Marco,

    Yes, just change




    This is mention on our VIP page, but it is easily missed, so we are in the process of getting a new certificate that will allow it to work without changing the host. In the meantime applying the above change should resolve the issue.

    In any case, please let me know if I can assist further.
    Kind regards

  • Marco

    Thank you for your quick response! Yes, this worked, thank you!

  • Charly B

    Can you add Florida, MA USA?

  • lricoy

    That’s a really great resource! Thanks

  • Deepa G

    Can you please add these 3 places in Indonesia?

    Ambon, Maluku
    Makassar, South Sulawesi

  • Deepa G

    Is there any way where I could add cities to the list? There are so many cities missing which I would like to add in this.

  • Deepa G

    Can you please add the following cities in Indonesia

    Ambon, Maluku
    Makassar, South Sulawesi

  • Terry

    I can’t get the code to work, I copy it an paste it into one of my webpages and it doesn’t work, what could cause it not to work?

  • Jan

    Any possibility to localize city names?
    I want to type “München” for the city munich. Since i am in Germany.

  • simer

    Hi very interesting tool, thank you.
    is there a way to list unique values for cities? if I truncate of the state and coutry?

  • Kevin

    How i can limit the result to 5? thanks

  • Sourabh

    Cant use this anymore because adblocker is blocking the request. and nower days alot people use adblockers

  • epetre

    Is there a way to get only major cities with airports? Without the smaller cities in the surroundings?

    Great job by the way this service is awesome!

  • Abelardo Dzib Batun

    Very cool!! please add La Habana, Cuba

  • Gaurav Jain

    Hi, We need to support multiple languages for AutoComplete Cities API. Is there any way to get cities names in multiple languages ?

  • Mikhail Shelemetyev

    that does not seem to be working now:(

  • CognitiveThinking

    Yes, we’re very sorry about the disruption.
    It is working again now, but we are still trying to get to the source of the issue.
    BTW I replied to your facebook message.

  • CognitiveThinking

    Sorry, but we don’t provide multiple language support. However, if you happen to know of a good source of cities names in various languages, then please let us know, as we may be able to add them as an alias.

  • Dan

    Hie this is a good tool, however i would like to use only City and ISO2 Code.
    The problem is that when you set up like this you will get a lot of places repeated. I would suggest you to do something that allow to hide the repeating locations. Sorry for a bad english, hope you understood. Thanks

  • leon powell

    Hi, I am new to jquery. Can i clarify. All i have to do is cut and paste into a html file and run it in my browser and it should automatically find a city that i type in. Just when i do this it doesn’t work. From the comments it seems that it works for everyone else so i would love to know where i am going wrong.

    Love the site by the way.



    I love the AJAX AUTOCOMPLETE LIST CITIES feature. However, it seems to have stopped working. When I try it from the Geobytes web page, it sits and spins, and no suggestions appear. Is it me or is that feature no longer free? Thanks!

  • SD

    It appears to be going down a lot now a days.

  • Nathan Quinones

    Absolutely love the tool! How can I increase/decrease the number of cities returned? Is there a parameter that I can pass?

  • Jay

    Having an issue with the template feature, if you add something like:

    “http://gd.geobytes.com/AutoCompleteCity?callback=?&template=%20%20&q=” + request.term

    It returns to the fillable fields:

    Mars Hill Maine <geobytes countr

  • John Hopkins

    Saint Louis, MO, United States is missing.

  • Joris

    There is quite some data missing for belgium… Can’t seem to find Nazareth in belgium for example…

  • CognitiveThinking
  • Joris

    yes, I was not able to find this using the sample or the service as follow:

  • CognitiveThinking

    Thanks I will add the town of Nazareth, but with regards to the municipality of the same name – our list of cities is not intended to include municipalities, only cities.
    In any case, I also notice a number of significant Belgium cities missing from our database, so I will add these, and check for more. However, if you happen to know of a list of cities that I should check against, then please feel free to forward it to me at adrian at geobytes com.

  • Abdi Pranoto

    Timezone for Surakarta, Jawa Tengah, Indonesia is incorrect. it should be GMT+7 not +8

  • Robert Taylor Ca

    Seems to have different location when on the cell phone device..
    On the Desktop it knows I’m in Vancouver, however, when I’m on my Cell Phone… it thinks I’m in Illinois

  • Jhon Luif As

    Hello! A friend and I recently stumbled upon this great tool , and we wanted to use it for a web project.

    But apparently, the server that attends the calls doesnt have a ca certificate , so it shows as mixed-content in our webpage, and gets blocked by the browsers.

    I dont know if it’s much to ask, but we would certainly be very grateful if you could add the Certificate, so it doesnt get blocked.

    Thanks for your time, and props to you for developing such an amazing API.

  • Camilo

    Hi, is there a way to use this with HTTPS. My website didn’t accept it because everything is in HTTPS, so I get the following error in the console: Mixed Content: The page at ‘https://mydomain.com/’ was loaded over HTTPS, but requested an insecure script ‘http://gd.geobytes.com/AutoCompleteCity?callback=jQuery1124025795837662873833_1499998343045&q=med&_=1499998343046’. This request has been blocked; the content must be served over HTTPS.

    What else can I do?

  • Vladimir Tirado Márquez

    Hi. Can you add this city in Bolivia? Cobija, PA, Bolivia
    and correct this city from “Trinidad, PA, Bolivia” to “Trinidad, BE, Bolivia”

  • JohnWiick

    Is this still working? Tried to use this code without any luck.

  • Dhanancheziyan

    First of all… Great work. Helped me reduce a lot of time in developing address section for user registration page.

    One request through, is it possible to add zipcode and country code (ISD code) in the response?

  • George Nicholas

    same issue with my site, we will be using something else because of this issue.

  • Camilo

    In the end I used http://easyautocomplete.com/

  • Ed Knittel

    Were you able to use Easy Autocomplete to search by a city name and get the lat and lng of the selected result? What data source are you using if you aren’t using gd.geobytes?

  • Camilo

    No, I only needed the cities and that’s why I could use Easy Autocomplete. You have to add this data manually.

  • Ed Knittel

    Thanks for the reply, Camilo. I ended up using my own cities.json file that I host for the data and easyAutocomplete for the front-end logic.

  • Neil Soper

    Hi, I was wondering if its possible to get a list of the country values that are returned by the service. I’d like to use the country to cross reference another data set but for it ot be reliable I would need a list of all the possible countries. is that available? Thanks.

  • Neil Soper

    Hi, this is a great service but I have noticed that Naypyitaw in Burma is missing.

  • Carlos

    It is possible to load only the cities of one country? Exmple ITaly, and how comes if i put my village : CALUSO, nothing come up here in the demo? thanks in advance for your help

  • Guillaume Maka

    First for set of useful api, just what I need when I needed it. Second do you provide «https» support?

  • David Moreno

    Can you change the name of Mexico, DF? It’s now called Mexico City.
    Also, a lot of Mexican cities are missing, can you update that?

  • Manoj Web Developer

    Thank You

– because everybody's somewhere