Bulk processing API documentation

Content

API usage rules

Number of terms
The maximum allowed number of terms is 100,000.
Result storing
The result is stored for 7 days.
Cost
1 credit per term.

Making requests

POSThttps://geoipify.whoisxmlapi.com/api/bgservice/

In order to check lists of terms with the Bulk API, first upload the terms to the server which will create a request and return its ID to you. Then you can use this ID to query the request's status, download results etc.

The API expects parameters to be JSON-encoded in the body of each request.

Headers

Content-Type
application/json

Create a new request

POSThttps://geoipify.whoisxmlapi.com/api/bgservice/request

CURL request sample

        curl https://geoipify.whoisxmlapi.com/api/bgservice/request -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "terms": ["alex@hotmail.edu", "8.8.8.8", "yahoo.com"], "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "terms": [
        "alex@hotmail.edu",
        "8.8.8.8",
        "yahoo.com"
    ],
    "format": "json"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
terms
Required. Array.

Contains array of IPs, emails, domain names for getting geolocaton.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".

Sample output

                            {
    "response": {
        "id": 5
    }
}

Code: 200 OK.
                            {
    "response": {
        "errors": [
            "The format field should have one of the following values: json, xml."
        ]
    }
}

Code: 400 Bad Request.
                            {
    "response": {
        "error": "Authorisation or authentication failed"
    }
}

Code: 401 Unauthorized.
                            {
    "response": {
        "error": "Insufficient balance"
    }
}

Code: 402 Payment Required.
response
The response object.

Contains the integer "id" field on success.

In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.
id
Integer.

Newly created request ID.
error
String.

Error description.
errors
Array.

Multiple error messages.

Get a list of your requests

POSThttps://geoipify.whoisxmlapi.com/api/bgservice/request/list

CURL request sample

        curl https://geoipify.whoisxmlapi.com/api/bgservice/request/list -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "page": 1, "onlyIds": false, "perPage": 10, "sort": "desc", "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "page": 1,
    "format": "json",
    "onlyIds": false,
    "perPage": 10,
    "sort": "desc"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
page
Optional. Integer.

Used to paginate the result sets in conjunction with "perPage".

Default value: 1.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".
onlyIds
Optional. Boolean.

When it's true only the list of IDs is returned.

Default value: true.
perPage
Optional. Integer.

Limits each page of the result-set to this number of requests.

Min: 10; Max: 50.

Default value: 10
sort
Optional. String.

Specify the order of requests in the response.

Allowed values: "asc", "desc".

Default value: "desc".

Sample output

                            {
    "response": {
        "current_page": 1,
        "data": [
            {
                "id": 596
            },
            {
                "id": 595
            },
            {
                "id": 544
            }
        ],
        "from": 1,
        "last_page": 1,
        "per_page": 10,
        "to": 3,
        "total": 3
    }
}

Code: 200 OK.
                            {
    "response": {
        "current_page": 1,
        "data": [
            {
                "id": 596,
                "date_start": "1528377253",
                "total_terms": 3,
                "invalid_terms": 0,
                "processed_terms": 3,
                "failed_terms": 0,
                "ready": 1
            },
            {
                "id": 595,
                "date_start": "1528377227",
                "total_terms": 20,
                "invalid_terms": 0,
                "processed_terms": 20,
                "failed_terms": 0,
                "ready": 1
            },
            {
                "id": 544,
                "date_start": "1528204702",
                "total_terms": 500,
                "invalid_terms": 0,
                "processed_terms": 500,
                "failed_terms": 0,
                "ready": 1
            }
        ],
        "from": 1,
        "last_page": 1,
        "per_page": 10,
        "to": 3,
        "total": 3
    }
}

Code: 200 OK.
response
The response object.

Contains the "data" field with an array of user's requests' data on success.

The "from" and "to" fields represent the result set's ID range of the requests returned for the current page.

"per_page" is the pages' size and "total" is the number of requests in the result set.

The "current_page" and "last_page" correspond to the number of pages in the result set.

In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.
data
Array.

A list of your requests' info elements (if "onlyIds" is true, each element has only the "id" field).
data[k].id
The response object.

Request ID.
data[k].date_start
String.

String representation of the request's start Unix timestamp.
data[k].total_terms
Integer.

The total of number of terms (IPs, emails, domain names) in the request.
data[k].invalid_terms
Integer.

Number of invalid terms.
data[k].processed_terms
Integer.

Number of already processed terms.
data[k].failed_terms
Integer.

Number of terms that could not be processed.
data[k].ready
Integer.

1 if processing has finished, 0 – otherwise.
from
Integer.

Min. request ID in the current page of the data set.
to
Integer.

Max. request ID in the current page of the data set.
per_page
Integer.

Max. number of requests for each page of the result set.
total
Integer.

The total number of requests in the result set.
current_page
Integer.

Current page number in the result set.
last_page
Integer.

The number of the last page in the set.
error
String.

Error description.
errors
Array.

Multiple error messages.

Get request's status

POSThttps://geoipify.whoisxmlapi.com/api/bgservice/request/status

CURL request sample

        curl https://geoipify.whoisxmlapi.com/api/bgservice/request/status -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "ids": [622], "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "ids": [544, 595, 596],
    "format": "json"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
ids
Required. Array.

Required requests' IDs.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".

Sample output

                            {
    "response": [
        {
            "id": 544,
            "date_start": "1528204702",
            "total_terms": 500,
            "invalid_terms": 0,
            "processed_terms": 500,
            "failed_terms": 0,
            "ready": 1
        },
        {
            "id": 595,
            "date_start": "1528377227",
            "total_terms": 20,
            "invalid_terms": 0,
            "processed_terms": 20,
            "failed_terms": 0,
            "ready": 1
        },
        {
            "id": 596,
            "date_start": "1528377253",
            "total_terms": 3,
            "invalid_terms": 0,
            "processed_terms": 3,
            "failed_terms": 0,
            "ready": 1
        }
    ]
}

Code: 200 OK.
response
The response object.

Contains an array of user's requests' info on success. This array can be empty in case the "ids" array contains non-existing ids only.

In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.

Get results (processed terms)

POSThttps://geoipify.whoisxmlapi.com/api/bgservice/request/completed

CURL request sample

        curl https://geoipify.whoisxmlapi.com/api/bgservice/request/completed -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "id": 622, "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "id": 596,
    "format": "csv"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
id
Required. Integer.

ID of the request.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".

Sample output

                            {
  "response": [
    [
      {
        "ip": "8.8.8.8",
        "location": {
          "country": "US",
          "region": "California",
          "city": "Mountain View",
          "lat": 37.40599,
          "lng": -122.078514,
          "postalCode": "94043",
          "timezone": "-07:00"
        },
        "domains": [
          "0.cnxelg.top",
          "000180.top",
          "0002.by",
          "00049ok.com",
          "001998.com.he2.aqb.so"
        ],
        "as": {
          "asn": 15169,
          "name": "Google LLC",
          "route": "8.8.8.0/24",
          "domain": "https://about.google/intl/en/",
          "type": "Content"
        },
        "isp": "Google",
        "term": "8.8.8.8"
      }
    ],
    [
      {
        "ip": "2607:f8b0:4007:804::2005",
        "location": {
          "country": "US",
          "region": "California",
          "city": "Mountain View",
          "lat": 37.38605,
          "lng": -122.08385,
          "postalCode": "94041",
          "timezone": "-07:00"
        },
        "isp": "Google",
        "term": "gmail.com"
      },
      {
        "ip": "172.217.11.165",
        "location": {
          "country": "US",
          "region": "California",
          "city": "Mountain View",
          "lat": 37.40599,
          "lng": -122.078514,
          "postalCode": "94043",
          "timezone": "-07:00"
        },
        "domains": [
          "lax28s15-in-f5.1e100.net"
        ],
        "as": {
          "asn": 15169,
          "name": "Google LLC",
          "route": "172.217.0.0/16",
          "domain": "https://about.google/intl/en/",
          "type": "Content"
        },
        "isp": "Google",
        "term": "gmail.com"
      }
    ]
  ]
}

Code: 200 OK.
                            {
    "response": {
        "error": "Wrong request id"
    }
}

Code: 422 Unprocessable Entity.
response
The response object.

Contains an array of geolocations for each IP address in the original request. See the documentation to get more info.

Responses to these request can be saved directly to disk.

In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.

Get results (Invalid and failed terms)

POSThttps://geoipify.whoisxmlapi.com/api/bgservice/request/failed

CURL request sample

        curl https://geoipify.whoisxmlapi.com/api/bgservice/request/failed -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "id": 622, "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "id": 596,
    "format": "csv"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
id
Required. Integer.

ID of the request.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".

List of possible errors

400 Bad Request
Some required fields are missing from the request's body or have invalid values.
401 Unauthorized
The required "apiKey" field value is missing or invalid.
402 Payment Required
Insufficient API queries account balance.
403 Forbidden
The request you're trying to access doesn't belong to your account.
422 Unprocessable Entity
The request you're trying to access doesn't belong to your account.
5XX
Internal server error, please contact our support team.
Try our IP Geolocation API for free
Get started
Have questions?

We work hard to improve our services for you. As part of that, we welcome your feedback, questions and suggestions. Please let us know your thoughts and feelings, and any way in which you think we can improve our product.

For a quick response, please select the request type that best suits your needs. For more info regarding the request types, see the Contact us page.

Or shoot us an email to