Geobytes IP Location APIs

Geolocation and IP Location API’s
Geobytes provides the following mostly free JSON  / JSON-P geographic and Geolocation APIs:

API Description Format Free per hour
GeoIf Search and Replace placeholders with the user's location details JavaScript 1024 per site visitor
GeoDirection Sets JavaScript variables to the users location JavaScript 1024 per site visitor
GeoPhrase Inserts a dynamic geographic phrase via JavaScript JavaScript
1024 per site visitor
GeoFlag Inserts an image of the site visitor county's flag via JavaScript JavaScript
1024 per site visitor
GeoRemote Returns the location of an IP Address, formatted according to a user defined template – utilises IP Address authentication User defined template na
use Get City Details API  for free access
AutoCompleteIp AJAX Autocomplete IP Address facility JSON-P
4096 per site visitor
AutoCompleteCity AJAX Autocomplete City facility JSON-P
4096 per site visitor
GetCityDetails Provides city attributes as a JSON, given either the IP Address, the Fully Qualified City Name (FQCN), or the Geobytes Location Code JSON-P
GetLocation Our classic IP locator API. Returns the location of an IP Address formatted according to a user defined template. Uses access credentials authentication User defined template na
use Get City Details API  for free access
GetDistance Returns the distance between two cities in either miles or kilometres, given either the IP Address, the Fully Qualified City Name (FQCN), or the Geobytes Location Code for each city JSON-P
Get Nearby Cities Provides a list of cities that are geographically close to the nominated city, given either an IP Address, a Fully Qualified City Name (FQCN), or a Geobytes Location Code JSON-P
Reasonable Free Access Limits

The free reasonable usage limits listed above are calculated based on usage over a one hour period.  So while the average usage limit may be 4.5 lookups per second (16,384/3600) our system does not cap your access the moment that you exceed that rate.  It aims to take into account your usage over the entire 60 minutes, but does not count every request either – here is a simplified explanation of how it works. (Simplified, because in practice we use two 30 minute time windows to effectively double the allowable peek rates while maintaining the overall hourly limit. )

In practice, rather than incurring the overhead of counting and tracking  every access, we use a statistical sampling method to estimate usage.  How it actually works is a little complicated, but for those that wish to know the details, we take the square-root of the access limit – let’s call it the sample rate, and then randomly select “for audit” requests at that sample rate.  Once a request is selected for audit, then its details are added to a cache where they will only be processed if a request with matching details is randomly selected again within the same 60 minute period.

If a matching request is identified a second time then we add the request’s details to a “tracked usage cache”.  All incoming requests are checked against the”tracked usage cache” and when a match is found the request is handled according to the state of any associated Mapbytes account.  If there is no associated Mapbytes account, or the account is empty, then the request is handled as a failed lookup and an “unknown” response is returned.  Alternatively, if a viable Mapbytes account is found, then one Mapbyte is deduced from that account, and the request is processed normally.

This approach facilitates an efficient response to  denial-of-service (DoS) attacks, because  we only need to track the details of requests that have exceeded a reasonable usage limit, rather than maintaining a counter for every requester.


Excess look ups are charged at 1 Mapbyte each – that is 100th of a cent per lookup. You can purchase 100,000 lookups for $9.99 via the Buy Now Button in the right margin.

  • Steve Hogan

    Hi. I am a low-volume user. Some time early on 14 Feb, IpLocator stopped working for me. Coming to your site, it appears that a lot has changed recently. In particular, I cannot find any documentation related to the method I am using. Here’s how I hit your server. $tags = get_meta_tags(‘’ . $user_IP . ‘&’); (Not my real password). I apologize if this is not the right way to contact you but I cannot find any contact info on your site. Thanks.

    Steve Hogan

  • Hi Steve,
    Sorry for the disruption to our services – that has resulted from our recent upgrades. Our IP Locator service (that you refer to) is currently working on, but not on, so at this stage the best option may be to update your script to:

    $tags = get_meta_tags(‘’ . $user_IP . ‘&’);

    Alternatively, and perhaps a even better option would be to switch to our GetCityDetails API – like this:

    $tags=json_decode(file_get_contents(''. $user_IP ), true);

    This will provide you with access to over 16,000 free lookups per hour.

    In any case, I am keen to help, so please let me know if I can assist further.

  • Petr Kokorev

    Hello, is there a way to get the complete list of “Geobytes Location Code”s?

  • CognitiveThinking

    Yes, you can download the raw data here:
    but better still there are sample queries on this page: and even a script to download and import the data if you are on linux, with mysql.
    Alternatively, if you just want a single CSV file with LocationCode, Fully Qualified City Name, Latitude, and longitude etc, then please just let me know exactly which fields that you require and I will dump the data out for you.
    In any case, please let me know if I can assist further.

  • I’d like to take my database of people’s names and overlay them on an IP map to determine IPs for each name on the list.

    I’d want to do this daily via API. Do you provide a service that will match my names to their corresponding IPs?

  • We also have physical addresses which is probably easier to match.

  • Ian Lewis

    Hi. What is the SSL endpoint for the API?
    We have some code using
    However switching to fails with an SSL certificate error.
    We are moving to SSL everywhere. Can you suggest a solution for handling your API endpoints?

  • Courthead

    Replace “gd” with “secure” in the URL. They send you the instructions in the email after you pay (which went straight into my spam box)

  • devender pal

    I just Buy the VIP

  • devender pal

    How to use it

  • This is what I needed for my project.

  • marco

    Is there a way to report bugs? My city (Gießen) contains a “ß” and the query results gets truncated to “Gie” – so, there might be a problem with “ß” and maybe other German umlauts?

– because everybody's somewhere