IP Vigilante is an API to get the geographical information of a IP.
It returns various formats: JSON and CSV.
You can query independent elements, like the country or the city, or 2 groups of information: default and full groups.
Query format
The query format is
https://ipvigilante.com/{format}/{IP}/{params}
where:
- format: json or csv.
- IP: the requested IP (v4).
- params: used to obtain only some specific information, like the country, the city or a group of information. It can be individual fields or field groups.
A query example is
https://ipvigilante.com/json/8.8.8.8
The returned JSON is
{ "status": "success", "data": { "ipv4": "8.8.8.8", "continent_name": "North America", "country_name": "United States", "subdivision_1_name": "California", "subdivision_2_name": null, "city_name": "Mountain View", "latitude": "37.38600", "longitude": "-122.08380" } }
Format
The API supports 2 response formats:
- JSON. We use de Jsend recomendation. JSend is a specification that lays down some rules for how JSON responses from web servers should be formatted.
- CSV.
Individual fields
You can get this individual fields from an IP:
- ipv4: the queried IP. E.g. 8.8.8.8.
- hostname: the host name. E.g. google-public-dns-a.google.com.
- continent_code: the continent code for this location. E.g. NA.
- continent_name: the continent name for this location. E.g. North America.
- country_iso_code: a two-character ISO 3166-1 country code for the country associated with the location. E.g. US.
- country_name: the country name for this location. E.g. United States.
- subdivision_1_iso_code: a string of up to three characters containing the region-portion of the ISO 3166-2 code for the first level region associated with the IP address. E.g. CA.
- subdivision_1_name: the subdivision name for this location. E.g. California.
- subdivision_2_iso_code: a string of up to three characters containing the region-portion of the ISO 3166-2 code for the second level region associated with the IP address. E.g. NTT.
- subdivision_2_name: the subdivision name for this location. E.g. Nottinghamshire.
- city_name: the city name for this location. E.g. Mountain View.
- metro_code: the metro code for this location. These are only available for networks in the US. These are the same metro codes as used by DoubleClick. E.g. 807.
- time_zone: the time zone associated with the location, as specified by the IANA Time Zone Database. E.g. America/Los_Angeles.
- postal_code: the postal code for this location. These are available for some locations in Australia, Canada, France, Germany, Italy, Spain, Switzerland, United Kingdom, and the US. E.g. 94035.
- latitude: the approximate latitude of the location associated with the network. E.g. 37.38600.
- longitude: the approximate longitude of the location associated with the network. E.g. -122.08380.
- accuracy_radius: The radius in kilometers around the specified location where the IP address is likely to be. E.g. 1000.
E.g., you can query the country_name field:
https://ipvigilante.com/json/8.8.8.8/country_name
The returned JSON is
{ "status": "success", "data": { "country_name": "United States" } }
Field groups
You can query on the specific field or a field group. Ipvigilante supports 2 groups:
- default
- full
In this examples, you can see the returned fields with each group
default
https://ipvigilante.com/json/8.8.8.8/default
This is the default query, so you can avoid this field
https://ipvigilante.com/json/8.8.8.8
The returned fields are
- ipv4
- continent_name
- country_name
- subdivision_1_name
- subdivision_2_name
- city_name
- latitude
- longitude
The returned JSON is
{ "status": "success", "data": { "ipv4": "8.8.8.8", "continent_name": "North America", "country_name": "United States", "subdivision_1_name": "California", "subdivision_2_name": null, "city_name": "Mountain View", "latitude": "37.38600", "longitude": "-122.08380" } }
full
https://ipvigilante.com/json/8.8.8.8/full
This request causes a slower query, so you only should use it if you need any of the fields not returned in the default group query.
The returned fields are
- ipv4
- hostname
- continent_code
- continent_name
- country_iso_code
- country_name
- subdivision_1_iso_code
- subdivision_1_name
- subdivision_2_iso_code
- subdivision_2_name
- city_name
- metro_code
- time_zone
- postal_code
- latitude
- longitude
- accuracy_radius
The returned JSON is
{ "status": "success", "data": { "ipv4": "8.8.8.8", "hostname": "google-public-dns-a.google.com", "continent_code": "NA", "continent_name": "North America", "country_iso_code": "US", "country_name": "United States", "subdivision_1_iso_code": "CA", "subdivision_1_name": "California", "subdivision_2_iso_code": null, "subdivision_2_name": null, "city_name": "Mountain View", "metro_code": 807, "time_zone": "America/Los_Angeles", "postal_code": "94035", "latitude": "37.38600", "longitude": "-122.08380", "accuracy_radius": 1000 } }
Errors
If the request is incorrect, you will receive a JSON with an error response. E.g., if you made the request with an incorrect IP:
https://ipvigilante.com/8.8.8.a/full
You get this JSON
{ "status": "error", "errors": [ { "code": "400.1", "message": "First parameter is incorrect", "numberErrors": 1 } ] }
The first element, the “status” shows the error.
In the second element, the “errors”, you get more information, so you can detect the possible error
Code |
Message |
Number of errors |
---|---|---|
400.1 | First parameter is incorrect | 1 |
400.2 | Second parameter is incorrect | 1 |
400.3 | Third parameter is incorrect | 1 |