| 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 example |
1024 per site visitor |
| GeoFlag | Inserts an image of the site visitor county's flag via JavaScript | JavaScript example |
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 example |
4096 per site visitor |
| AutoCompleteCity | AJAX Autocomplete City facility | JSON-P example |
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 example example example |
16,384 |
| 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 example |
16,384 |
| 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 example example example |
16,384 |
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.