Geo aggregations lets you collect analytics data for API calls based on geographical attributes such as region, continent, country, and city. From this analytics data, you can view a GeoMap in the New Edge UI that shows the location of API requests: ![GeoMap dashboard in the New Edge UI](https://docs.apigee.com/static/api-platform/images/geomap-dashboard2.png) Geo aggregations work by extracting geographical data from a third-party database and adding it to the analytics data collected by Edge. The geographical information can contain the city, country, continent, time zone, and region of a request made to an API proxy. To use geo aggregation, you must purchase the Maxmind GeoIp2 database that contains this geographical information. See for more information. > [!NOTE] > **Note:** Geo aggregations require that the IP address of a machine making the request to the API proxy is in the Maxmind GeoIp2 database. Otherwise, Edge cannot determine the location of the request. ## Enabling geo aggregation By default the geo aggregations are not enabled. To enable geo aggregations, you must: - On all Qpid servers, install the MaxMind database and configure the Qpid server to use it. - Enable the Geo Map display in the New Edge UI. ### Install the MaxMind database on all Edge Qpid servers Use the following procedure to install the MaxMind database on all Edge Qpid servers: 1. Obtain the Maxmind GeoIp2 database. > [!NOTE] > **Note:** Geo aggregations work by adding geographical data from a third-party database to the analytics data collected by Edge. To use geo aggregation, you must purchase the Maxmind GeoIp2 database that contains this information. See for more information. 2. Create the following folder on the Qpid server node: ``` /opt/apigee/maxmind ``` 3. Download the Maxmind GeoIp2 database to `/opt/apigee/maxmind`. 4. Change the ownership of the database file to the 'apigee' user: ``` chown apigee:apigee /opt/apigee/maxmind/GeoIP2-City_20160127.mmdb ``` 5. Set the permissions on the database to 744: ``` chmod 744 /opt/apigee/maxmind/GeoIP2-City_20160127.mmdb ``` 6. Set the following tokens in `/opt/apigee/customer/application/qpid-server.properties`. If that file does not exist, create it: ``` conf_ingestboot-service_vdim.geo.ingest.enabled=true conf_ingestboot-service_vdim.geo.maxmind.db.path=/opt/apigee/maxmind/GeoIP2-City_20160127.mmdb ``` If you stored the Maxmind GeoIp2 database in a different location, edit the path property accordingly. Note that this database file contains a version number. If you later receive an updated database file, it might have a different version number. As an alternative, create a symlink to the database file and use the symlink in `qpid-server.properties`. For example, create a symlink for "GeoIP2-City-current.mmdb" to "GeoIP2-City_20160127.mmdb". If you later receive a new database with a different file name, you only have to update the symlink rather than having to reconfigure and restart the Qpid server. 7. Change ownership of the `qpid-server.properties` file to the 'apigee' user: ``` chown apigee:apigee /opt/apigee/customer/application/qpid-server.properties ``` 8. Restart the Qpid server: ``` /opt/apigee/apigee-service/bin/apigee-service edge-qpid-server restart ``` 9. Repeat this process on every Qpid node. 10. To validate that geo aggregation is working: 1. Trigger several API proxy calls on a sample API proxy. 2. Wait about 5 - 10 mins for the aggregations to complete. 3. Open a console and connect to the Edge Postgres server: ``` psql -h /opt/apigee/var/run/apigee-postgresql/ -U apigee -d apigee ``` 4. Perform a SELECT query on the table analytics.agg_geo to show the rows with geographical attributes: ``` select * from analytics.agg_geo; ``` You should see the following columns in the query results which are extracted from the Maxmind GeoIp2 database: `ax_geo_city, ax_geo_country, ax_geo_continent, ax_geo_timezone, ax_geo_region`. If the `agg_geo` table is not getting populated, check the Qpid server logs at `/opt/apigee/var/log/edge-qpid-server/logs/` to detect any potential exceptions. ### Enable Geo Maps in the New Edge UI Use the following procedure to enable Geo Maps in the New Edge UI: 1. Set the following token in `/opt/apigee/customer/application/management-ui.properties` to enable Geo Maps. If that file does not exist, create it: ``` conf_uebe_disableGeoMap=false ``` 2. Change ownership of the `management-ui.properties` file to the `apigee` user: ``` chown apigee:apigee /opt/apigee/customer/application/management-ui.properties ``` 3. Restart the New Edge UI: ``` /opt/apigee/apigee-service/bin/apigee-service edge-management-ui restart ``` 4. In the New Edge UI, select **Analyze \> End Users \> Geomap** to display the geo aggregation data. ## Updating the MaxMind GeoIp2 database MaxMind issues periodic updates to the Maxmind GeoIp2 database. If you receive an updated database, use the following procedure to install it on Edge: 1. Obtain the updated Maxmind GeoIp2 database. 2. Download the Maxmind GeoIp2 database to `/opt/apigee/maxmind`. 3. Check the name of the database file. If it is the same as the old file, as defined in `/opt/apigee/customer/application/qpid-server.properties`, proceed to the next step. However, if the file has a different name, you have to edit the `qpid-server.properties` file to specify the name of the new database file and then restart the Qpid server, as described above. As an alternative, you can create symlink to the file. For example, create a symlink for "GeoIP2-City-current.mmdb" to "GeoIP2-City_20160127.mmdb". If you later receive a new database with a different file name, you only have to update the symlink rather than having to reconfigure the Qpid server. 4. Change the ownership of the database file to the 'apigee' user: ``` chown apigee:apigee /opt/apigee/maxmind/GeoIP2-City_20160127.mmdb ``` 5. Set the permissions on the database to 744: ``` chmod 744 /opt/apigee/maxmind/GeoIP2-City_20160127.mmdb ``` 6. Restart the Qpid server: ``` /opt/apigee/apigee-service/bin/apigee-service edge-qpid-server restart ``` 7. Repeat this process on every Qpid node.