Every response of our web service includes a couple of fields: "query_status_code" and "query_status_description". The first field contains an "OK" if nothing bad happened and the geolocation was possible, or another value if something went wrong. The second field describes the code received in the first field.
Basically, the code in your website/application must check the value in the first field. If it contains an "OK", it should go ahead and extract the rest of the values from the response. If not, it should understand that something went wrong.
The following table lists all the possible values for these two fields, and also includes an additional explanation. You can also download a CSV (Comma Separated Value) file containing this list. If you have a requirement to import this list into a SQL database, the CSV format will make your job easier.
| Query Status Code | Query Status Description | Explanation |
|---|---|---|
| OK | Query successfully performed. | You will receive this code if nothing bad happened and the geolocation was possible. |
| MISSING_SERVICE_ACCESS_KEY | The Service Access Key is missing in the query string. | You didn't supply the "Service Access Key", therefore the web service doesn't know who you are. |
| INVALID_SERVICE_ACCESS_KEY | The Service Access Key is invalid. | You supplied a "Service Access Key", but it could not be found in our system. Therefore, the web service doesn't know who you are. |
| MISSING_IP_ADDRESS | The IP address parameter is missing in the query string. | This will happen if you called the web service to locate an IP address, but didn't supply the IP address. |
| INVALID_IP_ADDRESS | The IP address provided in the query string is invalid. | This will happen if you provided an invalid IP address. |
| LOOPBACK_IP_ADDRESS | You provided the IP address 127.0.0.1, also known as loopback or localhost. Geolocation is not possible. | The IP address 127.0.0.1 does not belong to the internet, it belongs to your local host. It is not necessary/possible to perform a geolocation with that IP address. |
| PRIVATE_IP_ADDRESS | You provided a private (local) IP address that belongs to your private network, not to the internet. Geolocation is not possible. | This means that you provided a private IP address, such as "192.168.1.1". It is not possible to perform a geolocation with a private IP address. |
| MISSING_RESPONSE_FORMAT_PARAMETER | The "format" parameter that specifies the response format (such as XML or JSON) is missing in the query string. | Starting with version 1.7 of our API, the "format" parameter is mandatory. |
| INVALID_RESPONSE_FORMAT | The value for the "format" parameter provided in the query string is invalid. | Please provide a valid value for the "format" parameter, such as "XML" or "JSON". |
| FREE_TRIAL_LICENSE_EXPIRED | Your free trial license has expired. | The 30-day free trial expired. Please get a paid subscription. |
| SUBSCRIPTION_EXPIRED | Your subscription has expired. Please renew it. | Your paid subscription expired, simple as that. If this happens, you should renew it. |
| ANONYMOUS_PROXY_OR_VPN | The IP address belongs to an anonymous proxy or VPN service. Geolocation is not possible. | In these cases, geolocation is not possible. |
| INTERNET_ACCESS_VIA_SATELLITE | The IP address belongs to an ISP that offers internet access to several countries through satellites. Geolocation is not possible. | It is not possible to locate the IP address, because it belongs to a pool of addresses that can be assigned to more that one country. |
| CALLBACK_ONLY_WITH_JSON_FORMAT | The callback parameter (which allows to use the JSONP communication technique) can only be provided with the JSON response format. | If you are using the "callback" parameter, that means that you want to receive a response with the JSONP technique. If that is true, "format=JSON" must be present in the query string. |
| INVALID_COMPACT_PARAMETER | The "compact" parameter provided in the query string has an invalid value. | The "compact" parameter provided in the query string has an invalid value. The valid values are "Y" and "N". |
| GEOLOCATION_INFO_NOT_AVAILABLE | It was not possible for our algorithms to geolocate this IP address. | It was not possible for our algorithms to geolocate this IP address. This happens with 0.05% of the IP addresses. |