Get Nearby Cities API

The Geobytes Get Nearby Cities API provides a list of cities that are geographically close to the nominated city. You can use it either client-side or server-side to programmatically determine the cities that are in the vicinity of given location, given the locations fully qualified city name, a Geobytes Location Code, or an IP Address.

In JavaScript, for example you might access this service like this:

Which produces an output of something like this:
Nearby Cities

Miles Kms City Bearing Direction

BTW If you would like to see a live real life example, then please checkout our IP Locator Page, and perhaps view the page’s source.

Alternatively, to use the API server side you might approach it something like we have here in this PHP example:


Parameter Discription Example
locationcode Either of
* Geobytes Location Code
* Fully Qualified City Name
* IP Address
defaults to location of current connection based on IP Address if optional Latitude and Longitude not provided
callback Used by JSON-P AJAX Calls. If unsure, just pass in a question mark as the call back ?
limit Optionally limit the number of rows returned
defaults to 10
radius Limits the results to cities within the given radius
defaults to 40km or 25 miles
minradius Excludes cities that are closer than the minradius from the results
defaults to 0
latitude Latitude of nominated location
defaults to location of current connection based on IP Address if Geobytes Location Code not provided
longitude Longitude of nominated location
defaults to location of current connection based on IP Address if Geobytes Location Code not provided


The response is a list of cities in the form of a JSON array of arrays – with each array being the following details of the nearby city. This link will open a new window containing sample results based on your current location.

Contains Description
[0] Bearing The compass bearing in degrees from the nominated city to the nearby city
[1] City Name The name of the nearby city
[2] Region or State Code The two letter region or state code
[3] Country Name The name of the nearby city's country
[4] Direction The rough direction rounded to one of the ordinal (or intercardinal) directions
[5] Nautical Miles Distance in Nautical Miles
[6] Internet Code The two letter Internet Code of the nearby City's Country
[7] Kilometres The distance in Kilometres
[8] Latitude The Latitude of the nearby city
[9] Geobytes Location Code The Geobytes Location Code of the nearby city
[10] Longitude The Longitude of the nearby city
[11] Miles The distance in Miles
[12] Region or State The name of the region or state of the nearby city


  • stausm1

    The radius option on the GET NEARBY CITIES API seems to be limited to 10 miles even when you enter higher distances such as 25mi. Lowering the distance works fine. Is it meant to be this way?

  • CognitiveThinking

    There are two parameters that influence the number of rows that are returned:
    1. Radius
    2. Limit
    Radius restricts the results to an area, while Limit just restricts the number of rows that are returned.
    It sounds to me like you may not be setting the Limit parameter, as the default is 10 rows – are you able to confirm that you have tried setting this higher – say to 50 ?
    If that does not resolve the issue, could you please post the details of the request that you are sending – including the Limit and radius parameters. so that I can try to reproduce the problem here.
    BTW I have been using the following request for testing – which appears to be working OK for me.

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

  • Luke van Lathum

    Hey, this does not return valid json, there is a error:

    There is an error when I run this:


  • CognitiveThinking

    Try it without the callback=? parameter, as that parameter causes it to return a JSON-P
    For example, this returns a plain JSON

  • Luke van Lathum

    Hey, yes I tried that one, without the callback it adds 2 “” (double quotes to the start of the array which causes another error. In the end I managed to do this:

    $nearby = file_get_contents(‘’.getIP());

    if($nearby != ‘null’){
    $nearbyjson=str_replace(array( ‘(‘, ‘)’,’?’,’;’ ), ”, $nearby);
    $nearbycities = json_decode($nearbyjson, false);

    foreach($nearbycities as $near){
    echo $near[1];


  • CognitiveThinking

    I see what you mean.
    I’ll get it fixed. (Could be a couple of days though.)

  • CognitiveThinking

    Done – you should find that it is returning a correctly formatted JSON now.

  • vksh mandhotra

    RESULT ARE are not consitent….

    It is returning same result for every value I changed for radius,longitude or latitude

    It look like that data is setting static some where

  • Rashmi Nalwad


    I am curious to know can I enter Pincode of the location and get the list of places around that location? I am not very sure what locationID to enter for ex places like Bangalore

  • Conor

    Feature request. I’d be happy to be told it’s already available 🙂
    minRadius parameter to enable searches like “What cities are roughly 500 miles from X?”

  • CognitiveThinking

    Great ideas – thanks for the suggestions.
    I have added the minRadius parameter, as per you suggestion.

    Here is an example request for your reference:

    With regards to limiting the results to Capitals Only…. While we record the name of the country’s capital in the Countries table, we don’t uniquely identify the capitol. For example, we record Washington as the capitol of the US, but as there are many Washingtons though out the US – the name Washington alone is not sufficient to uniquely identify it. The bottom line is that the new capitalsonly parameter will return any city that has the same name as the given country’s capital, so while this parameter sort of works – I am going to leave it undocumented, and unsupported. (I fixed it for Washington, DC but other counties may be affected.)

    In any case, thanks heaps for the suggestions, and please let me know if I can assist further.

  • Conor

    Thanks. This is great. One question: is something hardcoded to limit results to within 700km? I seem to get nothing over 700.

  • Ben Lowe, UK

    Is there a limit to the radius/minRadius? When I go above 700km for the minRadius then I get an empty array despite the radius being 10000km. I can imagine it might get a bit processor intensive as the minRadius is increased.

  • CognitiveThinking

    Yes, the limit for radius was 500, but I raised it to 700 when I added the minRadius parameter.
    However, I have now modified the code so that there will be no limit on radius for requests where CapitalsOnly is true.
    (The change should make it through to the server by this time tomorrow.)

  • CognitiveThinking

    Yes, radius is limited to 700. I have looked at trying to improved the efficiency of the API, but I could not identify anywhere where that I could make a significant improvement, so 700 is about as high as we can go with that sorry.

  • CognitiveThinking

    Just letting you know that that last change regarding the radius limit and the CapitalsOnly parameter has now make it through to our production sever.
    Please let us know if you encounter any issues, or if I can assist further.

  • Ben Lowe, UK

    No worries. Thanks.

  • Avigit Saha

    Is this API free too?

  • egrove

    Near by city API return each time different response we got,

    Note : we purchased your product GEObytes, I can’t find any link otr form to contact you guys.

  • Ranjith

    I get ssl error, secure connection cannot be made

  • Daniele

    Is there a way to track the incoming Geobytes Fully Qualified City Name of each page request and the associated redirection URL? I plan to redirect traffic from a domain name of mine to various subscribers and I want to be able to show the subscribers the number of redirections to their site in a given time period.

  • Vadim Korolov

    Hey i am getting an error : Failed to load No ‘Access-Control-Allow-Origin’ header is present on the requested resource.

  • Hi, could you solve this problem? I’m having the same answer.

  • Ben

    Hi. The API appears to truncate the place names if they contain special characters. e.g. which should be returning “Gießen” as the first town but it is truncated to “Gie”.
    All the best, Ben.

– because everybody's somewhere