<commit_before>## Maintainer Contact

<NAME>

<kirk (dot) mayo (at) solnet (dot) co (dot) nz>

## Requirements

* SilverStripe 3.2
* A driver to return the json/jsonp results

# SilverStripe-Regional

Using modern GeoIP lookup mechanisms, this SilverStripe module makes available the coordinates, postal code, city,
state, country, content, timezone, organization, and ISP to the SilverStripe instance and can open a frontend API
for static websites to take advantage of. It can be extended with GeoIP drivers to provide additional or custom contextual data.


## Composer Installation

  composer require marketo/silverstripe-regional

## Config

The current module uses a default path for the GeoIP database this is currently set to `/usr/share/GeoIP/GeoLite2-City.mmdb`
This can be changed via the yml config a example is below.
A model admin exists called GeoRegion which adds user defined fields to the result that is returned.
It retrieves the details to add via the country code which needs to match a country code in GeoRegion.

```
IPInfoCache:
  GeoPath: '/your/own/location/yourdb.mmdb'
```

You can also return the results as json by setting up a variable in the yml config under IPInfoCache
as per the example below, which also details how to specify the driver to use.

```
IPInfoCache:
  Driver: 'MarketoRegionalDriver'
  CORS: true
  jsonp: 'yourOwnJsonpFunction';
  GeoPathCity: '/usr/share/GeoIP/GeoIPCity.dat'
```

Another way to set the jsonp function is directly by using the get variable fn this will override anything
set by the yml config file as per the following example url.

```
http://marketo.local/geoip/192.168.3.11.jsonp?fn=MarketoLoad
```

If you want to allow third party javascript requests to query the service (like AJAX) you will need to set
the CORS flag in your yml config to true so that the `Access-Control-Allow-Origin` header gets sent back to
the requesting browser.

## GeoIP database

You will neeed to retrive a databse for the module to work with this will need to be stored
on the server and you may need to set the location of GeoPath under IPInfoCache in your config yml file.
The free databases can be downloaded from here <https://github.com/maxmind/GeoIP2-php>

## API endpoints

The curent endpoint returns a JSON object giving location details for the IP address.
The results default to json but they can also be returned as jsonp if this has been defined under
the config for IPInfoCache

```
http://YOURSITE/geoip/IPADDRESS
http://YOURSITE/geoip/IPADDRESS.json<commit_msg>Added example JS code for querying from third party<commit_after>## Maintainer Contact

<NAME>

<kirk (dot) mayo (at) solnet (dot) co (dot) nz>

## Requirements

* SilverStripe 3.2
* A driver to return the json/jsonp results

# SilverStripe-Regional

Using modern GeoIP lookup mechanisms, this SilverStripe module makes available the coordinates, postal code, city,
state, country, content, timezone, organization, and ISP to the SilverStripe instance and can open a frontend API
for static websites to take advantage of. It can be extended with GeoIP drivers to provide additional or custom contextual data.


## Composer Installation

  composer require marketo/silverstripe-regional

## Config

The current module uses a default path for the GeoIP database this is currently set to `/usr/share/GeoIP/GeoLite2-City.mmdb`
This can be changed via the yml config a example is below.
A model admin exists called GeoRegion which adds user defined fields to the result that is returned.
It retrieves the details to add via the country code which needs to match a country code in GeoRegion.

```
IPInfoCache:
  GeoPath: '/your/own/location/yourdb.mmdb'
```

You can also return the results as json by setting up a variable in the yml config under IPInfoCache
as per the example below, which also details how to specify the driver to use.

```
IPInfoCache:
  Driver: 'MarketoRegionalDriver'
  CORS: false
  jsonp: 'yourOwnJsonpFunction';
  GeoPathCity: '/usr/share/GeoIP/GeoIPCity.dat'
```

Another way to set the jsonp function is directly by using the get variable fn this will override anything
set by the yml config file as per the following example url.

```
http://marketo.local/geoip/192.168.3.11.jsonp?fn=MarketoLoad
```

## Accepting third party AJAX requests

If you want to allow third party javascript requests to query the service (like AJAX) you will need to set
the CORS flag in your yml config to true so that the `Access-Control-Allow-Origin` header gets sent back to
the requesting browser as per the example below.

```
IPInfoCache:
  Driver: 'MarketoRegionalDriver'
  CORS: true
  jsonp: 'yourOwnJsonpFunction';
  GeoPathCity: '/usr/share/GeoIP/GeoIPCity.dat'
```

Querying the API from a third party can be done with jQuery or AJAX.
A simple synchronous javascript example is below where you can 
just call the function requestInfo with the host and the request.


``` javascript
function requestInfo(host, request) {
    var xhr = new XMLHttpRequest();
    xhr.open("GET", host + request, false);
    xhr.send();

    return xhr.response;
}

// call with the following
// var result = requestInfo('http://192.168.0.1/', 'geoip/50.206.151.39.json');
```

## GeoIP database

You will neeed to retrive a databse for the module to work with this will need to be stored
on the server and you may need to set the location of GeoPath under IPInfoCache in your config yml file.
The free databases can be downloaded from here <https://github.com/maxmind/GeoIP2-php>

## API endpoints

The curent endpoint returns a JSON object giving location details for the IP address.
The results default to json but they can also be returned as jsonp if this has been defined under
the config for IPInfoCache

```
http://YOURSITE/geoip/IPADDRESS
http://YOURSITE/geoip/IPADDRESS.json
{'fraction_non_alphanumeric': 0.06543826416394007, 'fraction_numerical': 0.0075770621663509554, 'mean_word_length': 4.362880886426593, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1283248', 'n_tokens_mistral': 1740, 'n_tokens_neox': 1640, 'n_words': 800}