This entire repo is still under development and currently has only some basic functionality. Pull requests to fix some of the outstading Issues would be appreciated, developers of all experience level welcome.
Geograpy3 fixes issues caused by using Geograpy with later versions of Python 3 (specifically in the Spyder IDE of Anaconda, but should work with Pyhon 3 in general). Most functionalities have remained the same as in Geograpy (and Geograpy2) while others may have changed slightly to work in Python 3. Its core functionality is to extract place names from a URL or text, and add context to those names -- for example distinguishing between a country, region or city. For more information on installation, usage, and syntax, please continue reading below.
Grab the package using pip
and git
(this could take a few minutes)
Try using one of the following:
1. pip install git+git://github.com/jmbielec/geograpy3.git
2. pip install git+https://github.com/jmbielec/geograpy3.git
Import the module, give a URL or text, and presto.
import geograpy3
link = 'http://www.bbc.com/news/world-europe-26919928'
places = geograpy3.get_place_context(url = link)
text_input = "Perfect just Perfect! It's a perfect storm for Nairobi"
more_places = geograpy3.get_place_context(text = text_input)
Now you have access to information about all the places mentioned in the linked article.
places.countries
contains a list of country namesplaces.regions
contains a list of region namesplaces.cities
contains a list of city namesplaces.other
lists everything that wasn't clearly a country, region or city
Note that the other
list might be useful for shorter texts, to pull out
information like street names, points of interest, etc, but at the moment is
a bit messy when scanning longer texts that contain possessive forms of proper
nouns (like "Russian" instead of "Russia").
In addition to listing the names of discovered places, you'll also get some information about the relationships between places.
places.country_regions
regions broken down by countryplaces.country_cities
cities broken down by countryplaces.address_strings
city, region, country strings useful for geocoding
While a text might mention many places, it's probably focused on one or two, so Geograpy3 also breaks down countries, regions and cities by number of mentions.
places.country_mentions
places.region_mentions
places.city_mentions
Each of these returns a list of tuples. The first item in the tuple is the place name and the second item is the number of mentions. For example:
[('Russian Federation', 14), (u'Ukraine', 11), (u'Lithuania', 1)]
You can of course use each of Geograpy3's modules on their own. For example:
from geograpy3 import extraction
e = extraction.Extractor(url = 'http://www.bbc.com/news/world-europe-26919928')
e.find_entities()
# You can now access all of the places found by the Extractor
print(e.places)
Place context is handled in the places
module. For example:
from geograpy3 import places
pc = places.PlaceContext(['Cleveland', 'Ohio', 'United States'])
pc.set_countries()
print(pc.countries) #['United States']
pc.set_regions()
print(pc.regions) #['Ohio']
pc.set_cities()
print(pc.cities) #['Cleveland']
print(pc.address_strings) #['Cleveland, Ohio, United States']
And of course all of the other information shown above (country_regions
etc)
is available after the corresponding set_
method is called.
If you have found a bug or issue in Geograpy3, please submit a ticket to the Issues tab above, and describe in as much detail as possible all circumstances, inputs, and outputs surrounding said bug. Thank you for your help!
When creating a new branch that corresponds to an Issue, please include the Issue number at the end of the branch name.
Example: find-entities-fix-5 would correspond to Issue number 5 regarding the find_entities() method not working.
When creating a new pull request, again reference/link the Issue number the pull request is fixing so that Issues can be closed after merging.
For branches/pull requests unrelated to Issues, please use standard naming conventions and accurately describe the scope and goal of your code. If you have any questions do not hesitate to ask, thank you!
Geograpy3 was originally forked from lesingerouge's Geograpy, who originally forked from ushahidi's Geograpy, who I believe is the original creator of Geograpy. Geograpy3 also used some material and inspiration from Corollarium's Geograpy2.
Geograpy3 uses the following excellent libraries:
- NLTK for entity recognition
- newspaper for text extraction from HTML
- jellyfish for fuzzy text match
- pycountry for country/region lookups
Geograpy3 uses the following data sources:
- GeoLite2 for city lookups
- ISO3166ErrorDictionary for common country mispellings via Sara-Jayne Terp
Hat tip to Chris Albon for the name.
Released under the MIT license.