Home

VoIPGMap

Brief: A bash shell script which will read active call destinations in
E.164 format from a source (such as Asterisk), then run the called number
through some plain text and MySQL databases to find the best latitude/longitude
match. It then creates a .html file with Google Maps API JavaScript code
which will display a single call origination point and the active destinations
(calls) on a Google Maps world map.

LICENSE:

Use the script and the ITU and plain text databases as you wish. I do not hold
any rights regarding the MaxMind database which can be publicly downloaded at:
http://www.maxmind.com/download/worldcities
If you publish your map somewhere on the web, it would be nice if you could
eMail me the URL so that I can check it out. :-) Thanks!
eMail: universe@truemetal.org

DEMO:

1. http://truemetal.org/universe/voipgmap/live_demo1.html
2. http://truemetal.org/universe/voipgmap/live_demo2.html
3. http://truemetal.org/universe/voipgmap/live_demo3.html
4. http://truemetal.org/universe/voipgmap/live_demo4.html

One falling marker = one active call. Several markers can fall onto the same
spot and will only show as a single marker, usually when there are many calls
to mobiles (center of country) or when the exact coordinates couldn't get
located for some other reason. Use Chrome for best performance.

FEATURES:

-- You can feed any lines of E.164 numbers as call destinations to it, they
don't necessarily have to come from Asterisk or some other PBX.

-- Understands the difference between US and Canada.

-- Knows a pretty good location of most codes in the US.

-- Is aware of 1XXX codes, understands difference between US, Puerto Rico,
Dominica and all other countries whose code starts with "1".

-- Fetches destination code description from self-compiled database 100% based
on ITU data. (~190 or so Excel files/weblinks :-) ) See limitations at the
end of this page.

-- Looks up 3.1 million city lat/long entries, thanks to the open MaxMind database.
In theory, it can graph every single fixed line area code worldwide, but this
depends on the quality of the ITU database.

-- If no match found and for most mobile calls, uses fallback and graphs the
center of the called country instead.

-- Handles special characters, umlauts etc. in destination descriptions.

CONFIGURATION:

1. Get your own Google Maps API v3 key. See:
   https://developers.google.com/maps/documentation/javascript/tutorial#api_key

2. Create MySQL database (e.g. maps) and import "maps.db". Grant MySQL user
   SELECT permissions.

3. Copy "homeicon-maps.png" into the same directory where you will store
   the output html file, or create your own icon (22x22 px).

4. Find the coordinates where you want your calls to originate from. You could
   use: http://itouchmap.com/latlong.html

5. maps.sh config section:

6. Enter your API key.
7. Enter your MySQL credentials.
8. Adjust your call origination coordinates.
9. Optionally adjust map center coordinates.
10. Name of output file.
11. Specify your shell commands to read lines of E.164 numbers.

12. Optionally, copy the output file to a remote webserver (see end of
    maps.sh).

13. Run maps.sh, cross fingers, and open the output file in your browser.

14. Run it via cron, like once a minute or maybe every 5 minutes.

15. You're done!

WHAT IT DOES:

1. Reads lines of E.164 numbers and checks for a minimum length.

2. Figures out called country, fetches ISO code and coordinates of country center
   from text file (countries.txt). If we don't find a valid country code, don't
   graph that particular call.

3. If call to 1XXX: figures out whether US or Canada or another country. If US,
   fetches city and state from text file (us.txt).

4. For Canada and all other countries of the world: tries to intelligently find
   a reasonable description for the called code in the ITU database (table: plan1)
   by decrementing the called number by 1 digit until a match was found. If we
   don't find an ITU description, graph the call in the center of the country.

5. If a description was found, throw it at the MaxMind database (table: maxmind)
   in different combinations, until we find a match, to get more accurate
   coordinates. Do that for the city name in the local language (possibly with
   special characters, umlauts etc.) and for the English name of the city, as
   the description may be stored either with special chars or in plain English
   in the ITU database.

6. For the US, look up coordinates of city together with state in the MaxMind
   database. (US is the only country where MaxMind stores state names in the
   database - therefore we have to handle the US separately).

7. Multiple cities in the same ISO code or US state match? Use the city with
   the largest population.

8. If nothing matches in the MaxMind database, either because we don't have a
   good (or none) ITU description for that code or because it's a mobile or
   premium call, fall back to the center of the country.

9. Generate the .html file with Google Maps API JavaScript code from several
   template files (maps_template_*.txt) and optionally, upload the file to a
   webserver.

LIMITATIONS:

-- France, Spain and Argentina are not included in my ITU database, so for those
countries it will always graph the country center. Please let me know if I
should have forgotten other countries as well! Hm, I just realized that Italy
is also of poor quality... well, submissions are welcome! :-)

-- Shell script and calling the MySQL binary is slow. Feel free to rewrite
everything in PHP or something like that and probably optimize the SQL
queries. Let me know and we can put it up on the sourceforge site.

https://sourceforge.net/p/voipgmap

HAVE FUN.
END.

Project Admins:

• univ