Just a second...

Client Geo and WhoIs information

When a client connects to Diffusion™, information about that client's geographic location is looked up and the information is made available to publishers.

When a client first connects to a Diffusion server, its remote IP address is immediately available (using the Client.getRemoteAddress method) as well as other details obtained from the embedded GeoIp database. Further host and geographic details about the client are obtained using the Diffusion "WhoIs service".

GeoIp information

Diffusion ships with a GeoIP database from MaxMind. This provides information about Locale and geographic co-ordinates. The Java™ API includes utilities (GeoIPUtils) to make use of this database.

This is a public domain database and is free to use. You can purchase the more accurate database from MaxMind and change the configuration in the etc/Server.xml properties to use the new database.

The database can be disabled but its use is mandatory if you are going to use client connection or subscription validation policies.


The inbuilt WhoIs service can provide additional information about clients, however the lookup of the WhoIs information might take some time, especially if it is not already cached. This means that notification of the connection and further processing of the client cannot wait for this information to become available. For this reason the resolution of the client's WhoIs details is notified to client listeners separately from client connection on the clientResolved method.

When a client is first connected it is likely that the WhoIs details of the client are not available. This can be checked using the Client.isResolved method. When the details become available they can be obtained from the client using the getWhoIsDetails method which returns an object containing the following information:

Table 1. WhoIs
Address The client's IP Address – this is the same as that obtained using Client.getRemoteAddress.
Host The resolved host name of the client. If the host name cannot be resolved, the address is returned.
Resolved name The fully resolved name of the client. Exactly what this means depends upon the WhoIs provider in use. If a fully resolved name cannot be obtained, the host name value is returned.
Locale Returns the result of a geographic lookup of the IP address indicating where the address was allocated. The country of the locale is set to the international two-letter code for the country where the internet address was allocated (for example, NZ for New Zealand). If the internet address cannot be found in the database, the country and language of the returned locale are set to empty Strings.

Three country values can be returned that do not exist within the international standard (ISO 3166). These are EU (for a non-specific European address), AP (for a non-specific Asia-Pacific address) and ** (an internet address reserved for private use, for example on a corporate network not available from the public internet).

The language of the returned locale is set to the international two-letter code for the official language of the country where the internet address was allocated. Where a country has more than one official language, the language is set to that which has the majority of native speakers. For example, the language for Canada is set to English (en) rather than French (fr). Non-specific addresses (EU and AP), private internet addresses (**), and addresses not found within the database, all return an empty string for language.
WhoIsData This is data extracted from an enquiry upon a 'WhoIs' data provider.
Local Indicates whether the client address is a local address, in which case no locale or WhoIsData is available.
Loopback Indicates whether the client address is a loopback address in which case no locale or WhoIsData is available.