January 18, 2017 IP Vigilante

API Developer Docs

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