Geoparser.io is a RESTful web API that identifies place names mentioned in text, disambiguates those names, and returns GeoJSON for the places found in the text. Here's how you use it.
According to Wikipedia, geoparsing is the process of converting free-text descriptions of places (such as "Springfield") into unambiguous geographic identifiers (such as lat-lon coordinates). A geoparser is a tool that helps in this process. Geoparsing goes beyond geocoding in that, rather than analyzing structured location references like mailing addresses and numerical coordinates, geoparsing handles ambiguous place names in unstructured text.
Geoparser.io works best on complete sentences in English, like those shown in the example inputs below. If you have a very short text, such as a partial address like "Auckland New Zealand," you probably want to use a geocoder tool instead of a geoparser.
API Endpoint URI: https://geoparser.io/api/geoparser
Request Protocol: HTTPS POST
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Response Format: GeoJSON
Authentication: authorization token (
apiKey must be passed in HTTP request header, see examples below)
python -mjson.toolpretty-prints the JSON response, but is certainly not required.
$ pip install requests.
FeatureCollection.properties.idis a unique-ish identifier generated for each API request submitted.
Featureobject contains an id element with the corresponding
geonameidunique identifier from GeoNames.org.
Featurealso contains a
propertiesobject with the following elements:
Feature.properties.nameis the best name for the specified location, with a preference for official/short name forms (e.g., "New York" over "NYC," and "California" over "State of California"), which may be different from exactly what appears in the text.
Feature.properties.countryis the ISO-3166 2-letter country code for the country in which this place is located, or
NULLfor features outside any sovereign territory.
Feature.properties.admin1is a code representing the state/province-level administrative division containing this place. (From GeoNames.org: "Most adm1 are FIPS codes. ISO codes are used for US, CH, BE and ME. UK and Greece are using an additional level between country and fips code. The code '00' stands for general features where no specific adm1 code is defined.")
Feature.properties.typeis a text description of the geographic feature type — see GeoNames.org for a complete list. Subject to change.
Feature.properties.confidenceis a confidence score produced by the place name disambiguation algorithm. Currently returns a placeholder value; subject to change.
Feature.properties.referencesis an array of arrays, each element of which consists of two integers indicating the start (index of the first character in the place reference) and end (index of the first character after the place reference) of each reference to the this place name found in the input text.
"I was born in Springfield and grew up in Chicago."and notice how the response output changes, particularly for Springfield!
inputText, so the corresponding
Feature.properties.referencesarray contains multiple entries.
inputTextwas matched to a longer "official" name in the response output: "Province of Davao Oriental." The original text can always be retrieved from the
inputTextby using the index positions provided in the
Featureobjects for Aliwagwag, Mindanao, and Compostela (separately from Compostela Valley) — hey, nobody's perfect!
Geoparser.io uses the GeoNames.org geographical database as its primary source of gazetteer data. GeoNames.org was founded by Marc Wick, is maintained by the GeoNames Team, and is a project of Unxos GmbH, Switzerland. The GeoNames.org gazetteer contains data from dozens of sources and is licensed under a Creative Commons Attribution 3.0 License. For use in Geoparser.io, several modifications were made to address data quality issues and missing records in the GeoNames.org material.
Click below and let us know if you have any questions about using Geoparser.io!