Usage

User only need to send AJAX request to API in pre-defined format, the server at backend will respond the request at JSON format for user further use.

API URL

The registered user would have a unique API URL, please click My API button on the left menu.

API Parameters

To successfully get the response from server, below parameters are necessary with the request

Parameters Demo

Below shows how the parameters are set in Demo JS.
Caution:the USERNAME and SECRETKEY set in JS is for convenience of understanding how it works, but such private parameter should store in backend rather than in JS where public would know it.

const apiSet = {
    "apiUrl" : "www.yuguoo.com/z16app00016/api_WorldCity",
    "username" : "***",// DO NOT store in JS
    "secretkey" : "***",// DO NOT store in JS
    "user_langcode" : "local",/* "cn", "en" or "local" */
    "address_arrow" : "az",/* "az" or "za" */
    "default_nation": "",/* English name of the nation*/
    "suffix": "&isRequestingFromAPI=true",
}
        

Respose Data

Server responds API request with JSON data. There are 4 levels of information regarding a city.

Example of T1 level data responded from server is as below:

//JSON Response Data Format 
{"CityInfo_Dict":
    [
        {
        "id":1,
        "name_cn":"中国",
        "name_en":"China",
        "name_local":"中国",
        "code":"86",
        "parent_id":"0",
        "id_path":"0",
        "unique_code":"China,0"},
        {
        "id":3426,
        "name_cn":"美国",
        "name_en":"United States",
        "name_local":"United States",
        "code":"1",
        "parent_id":"0",
        "id_path":"0",
        "unique_code":"United States,0"}
    ]
}
        

Demo HTML

The HTML code of Demo are set forth below, for easy illustration, styles of elements had been removed.

        <div>
            <label>City</label>
            <div>
                <select name="City_T1_Selected" id="City_T1_Selected">
                    <option>- Nation/Region -</option>
                </select>
            </div>
            <div>
                <select name="City_T2_Selected" id="City_T2_Selected">
                   <option>- Province/State -</option>
                </select>
            </div>
            <div>
                <select name="City_T3_Selected" id="City_T3_Selected">
                   <option>- City/County Name -</option>
                </select>
            </div>
        </div>
        <div>
            <label>Location</label>
            <div>
                <select name="City_T4_Selected" id="City_T4_Selected">
                   <option>- District/Town -</option>
                </select>
            </div>
            <div>
                <input id="Location_Input" type="text" name="Location_Input" placeholder="input building number and street">
            </div>
        </div>
        <div>
            <label>Full Address</label>
                <div>
                    <p id="Full_Address"></p>
                </div>
        </div>
        

Demo JS

To minimize the dependance, the Demo JS code are mainly programmed by basic statement other than importing Jquery or other JS framework

/*******************************Demo JS***************************************************/   
    var apiSet = {
                "apiUrl" : "****",//need replace with effective
                "username" : "****",//need replace with effective, DO NOT store it in JS
                "secretkey" : "****",//need replace with effective, DO NOT store it in JS
                "user_langcode" : "local",
                "address_arrow" : "az",/* "az" or "za" means how address starts with nation or nation at the last*/
                "default_nation": "",/* English name of the nation which match with the one in the backend*/
                "suffix": "&isRequestingFromAPI=true",
            }

    window.onload = function () {
        // add onclick function to DOM object
        document.getElementById("City_T1_Selected").addEventListener('click', ajaxLoad_CityT1, false);
        // add onchange function to DOM object
        document.getElementById("City_T1_Selected").addEventListener('change', City_T1_SelChange, false);
        document.getElementById("City_T2_Selected").addEventListener('change', City_T2_SelChange, false);
        document.getElementById("City_T3_Selected").addEventListener('change', City_T3_SelChange, false);
        document.getElementById("City_T4_Selected").addEventListener('change', City_T4_SelChange, false);
        document.getElementById("Location_Input").addEventListener('change', Location_InputChange, false);
        if (apiSet['default_nation']!="") {ajaxLoad_CityT1()}//auto load T1 when default nation appointed
    }
    // once user re-selected the option item, 
    // add onclick function, restore the default option text
    var City_T2_DefaultOptionHtml = document.getElementById("City_T2_Selected").innerHTML
    var City_T3_DefaultOptionHtml = document.getElementById("City_T3_Selected").innerHTML
    var City_T4_DefaultOptionHtml = document.getElementById("City_T4_Selected").innerHTML
    function City_T1_SelChange(){
        document.getElementById("City_T2_Selected").innerHTML = City_T2_DefaultOptionHtml
        document.getElementById("City_T3_Selected").innerHTML = City_T3_DefaultOptionHtml
        document.getElementById("City_T4_Selected").innerHTML = City_T4_DefaultOptionHtml
        document.getElementById("City_T2_Selected").addEventListener('click', ajaxLoad_CityT2, false);
        document.getElementById("City_T3_Selected").addEventListener('click', ajaxLoad_CityT3, false);
        document.getElementById("City_T4_Selected").addEventListener('click', ajaxLoad_CityT4, false);
        _getFullAddress()
    }
    function City_T2_SelChange(){
        document.getElementById("City_T3_Selected").innerHTML = City_T3_DefaultOptionHtml
        document.getElementById("City_T4_Selected").innerHTML = City_T4_DefaultOptionHtml
        document.getElementById("City_T3_Selected").addEventListener('click', ajaxLoad_CityT3, false);
        document.getElementById("City_T4_Selected").addEventListener('click', ajaxLoad_CityT4, false);
        _getFullAddress()
    }
    function City_T3_SelChange(){
        document.getElementById("City_T4_Selected").innerHTML = City_T4_DefaultOptionHtml
        document.getElementById("City_T4_Selected").addEventListener('click', ajaxLoad_CityT4, false);
        _getFullAddress()
    }
    function City_T4_SelChange(){
        _getFullAddress()
    }
    function Location_InputChange(){
        _getFullAddress()
    }

    function _getFullAddress(){
        var t1dom = document.getElementById("City_T1_Selected")
        var t1text = t1dom.options[t1dom.selectedIndex].text
        var t2dom = document.getElementById("City_T2_Selected")
        var t2text = t2dom.options[t2dom.selectedIndex].text
        var t3dom = document.getElementById("City_T3_Selected")
        var t3text = isNaN(parseInt(t3dom.value)) ? "" : t3dom.options[t3dom.selectedIndex].text
        var t4dom = document.getElementById("City_T4_Selected")
        var t4text = isNaN(parseInt(t4dom.value)) ? "" : t4dom.options[t4dom.selectedIndex].text
        var t5text = document.getElementById("Location_Input").value
        if (apiSet['address_arrow'] == "za"){
            var addList = [t5text,t4text,t3text,t2text,t1text]
            var htmlStr = ""
            for (var i = 0; i < addList.length; i++) {
                if (addList[i]!="") {htmlStr=htmlStr+addList[i]+", "}                
            }
            document.getElementById("Full_Address").innerHTML = htmlStr
        }else{
            var addList = [t1text,t2text,t3text,t4text,t5text]
            var htmlStr = ""
            for (var i = 0; i < addList.length; i++) {
                if (addList[i]!="") {htmlStr=htmlStr+addList[i]+", "}                
            }
            document.getElementById("Full_Address").innerHTML = htmlStr
        }
    }
    // 1 create xmlhttp object 创建xmlhttp对象
    var xmlhttp;
    if (window.XMLHttpRequest){//  IE7+, Firefox, Chrome, Opera, Safari 浏览器执行代码
        xmlhttp = new XMLHttpRequest();}
    else{// IE6, IE5 浏览器执行代码
        xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");}
    // 2 Functions
    function _url_get(cityParentID_selected = 0) {
        //cityParentID_selected = default 0, means no parent_id which
        //is top tier of the list, namely is nation or region
        var requestData = "username=" + apiSet["username"] +
                "&secretkey=" + apiSet["secretkey"] +
                "&user_langcode=" + apiSet["user_langcode"] +
                "&default_nation=" + apiSet["default_nation"] +
                "&cityParentID_selected=" + cityParentID_selected + apiSet["suffix"]
        var url_full = apiSet["apiUrl"] + 
            (apiSet["apiUrl"].indexOf("?")>=0 ? "&" : "?") + 
            requestData
        return encodeURI(url_full)
    }
    function _options_html(xmlhttp="", defaultHtml="check upper information") {
        var optionHtml = ""
        var defaultHtml = defaultHtml
        if (xmlhttp.readyState==4 && xmlhttp.status==200){
            var res = xmlhttp.responseText
            var res_json = eval("(" + res + ")")//transfer JSON string to Dict Format
            // console.log(res_json)// check server response
            if (res_json["CityInfo_Dict"].length) {
                for (var i = 0; i < res_json["CityInfo_Dict"].length; i++) {
                    var city_id = res_json["CityInfo_Dict"][i].id
                    //use English name as default
                    var city_name = res_json["CityInfo_Dict"][i].name_en
                    if (apiSet["user_langcode"] == "cn") {city_name = res_json["CityInfo_Dict"][i].name_cn}
                    if (apiSet["user_langcode"] == "local") {city_name = res_json["CityInfo_Dict"][i].name_local}
                    // assemble options in HTML
                    optionHtml = optionHtml + "<option value='"+
                        city_id+"'>"+ city_name+"</option>"
                }
            } else {
                optionHtml = defaultHtml
            }
        }else{
            optionHtml = "load city info failure!"
        }
        return optionHtml
    }
    function ajaxLoad_CityT1(argument) {//获取初始国家/地区数据
        var cityParentID_selected = 0
        document.getElementById("City_T1_Selected").innerHTML = "<option>...Loading...</option>"
        xmlhttp.onreadystatechange=function(){
            document.getElementById("City_T1_Selected").innerHTML = _options_html(xmlhttp,"")
            document.getElementById("City_T1_Selected").removeEventListener('click',ajaxLoad_CityT1,false);
        }
        xmlhttp.open("GET",_url_get(cityParentID_selected),true);
        xmlhttp.send();
        document.getElementById("City_T2_Selected").addEventListener('click', ajaxLoad_CityT2, false);
    }
    function ajaxLoad_CityT2(argument) {//获取T2需要向服务器提交T1信息
        var cityParentID_selected = document.getElementById("City_T1_Selected").value
        document.getElementById("City_T2_Selected").innerHTML = "<option>...Loading...</option>"
        xmlhttp.onreadystatechange=function(){
            document.getElementById("City_T2_Selected").innerHTML = _options_html(xmlhttp,City_T2_DefaultOptionHtml)
                document.getElementById("City_T2_Selected").removeEventListener('click',ajaxLoad_CityT2,false);
        }
        if (cityParentID_selected) {
            xmlhttp.open("GET",_url_get(cityParentID_selected),true);
            xmlhttp.send();
            document.getElementById("City_T3_Selected").addEventListener('click', ajaxLoad_CityT3, false);
        }
    }
    function ajaxLoad_CityT3(argument) {//获取T3需要向服务器提交T2信息
        var cityParentID_selected = document.getElementById("City_T2_Selected").value
        document.getElementById("City_T3_Selected").innerHTML = "<option>...Loading...</option>"
        xmlhttp.onreadystatechange=function(){
            document.getElementById("City_T3_Selected").innerHTML = _options_html(xmlhttp,City_T3_DefaultOptionHtml)
                document.getElementById("City_T3_Selected").removeEventListener('click',ajaxLoad_CityT3,false);
        }
        if (cityParentID_selected) {
            xmlhttp.open("GET",_url_get(cityParentID_selected),true);
            xmlhttp.send();
            document.getElementById("City_T4_Selected").addEventListener('click', ajaxLoad_CityT4, false);
        }
    }
    function ajaxLoad_CityT4(argument) {//获取T4需要向服务器提交T3信息
        var cityParentID_selected = document.getElementById("City_T3_Selected").value
        document.getElementById("City_T4_Selected").innerHTML = "<option>...Loading...</option>"
        xmlhttp.onreadystatechange=function(){
            document.getElementById("City_T4_Selected").innerHTML = _options_html(xmlhttp,City_T4_DefaultOptionHtml)
                document.getElementById("City_T4_Selected").removeEventListener('click',ajaxLoad_CityT4,false);
        }
        if (cityParentID_selected) {
            xmlhttp.open("GET",_url_get(cityParentID_selected),true);
            xmlhttp.send();
        }
    }

        

Source of Data

The City Data Information are from:

Data Snippet

Below snippet data are part of the Excel file, you can refer the structure of the sample data.

Pricing

The data is publicly accessible but compiling them into a neat and orgnized excel file which takes efforts. If you need a Excel file containing below data, here is the price:

Contact

Please contact us before you would like to pay any price. email is jim.guo at outlook dot com, or add friend in WeChat at JimGuo-wechat.

Tailored Data

We could source city data which not included into our database based on your request.

Tailored API & Server

If you have data and would like to transform it into a API service, we could provide technical support including coding and also setting up a separate cloud server to provide API service.

API Hosting

We could provide as a server to host your data, just like we hosting World City API.

If you think this API or information is helpful and would like to donate, blow QR codes are available to receive your donation.

Alipay

Please use Alipay App to scan

WeChat Pay

Please use WeChat App to scan

Contact

Please feel free to contact with us for any query or suggestion at jim.guo at outlook dot com