The function calls the geoparser.io API which identifies places
mentioned in the input text (in English), disambiguates those places, and
returns data about the places found in the text.
geoparser_q(text_input, key = geoparser_key())A vector of strings, where each size must be smaller than 8 KB. See
nchar(text_input, type = "bytes").
Your geoparser.io key.
A list of 2 data.frames (dplyr::tbl_dfs). The first
data.frame is called properties and contains:
apiVersion the version of the API currently in use
source the source of authority for the results
id the unique id of the query
text_md5 MD5 hash of the text that was sent to the API.
The second data.frame contains the results and is called results.
If there are no results it is totally empty, otherwise:
country ISO-3166 2-letter country code
for the country in which this place is located or NULL for features
outside any sovereign territory.
confidence A confidence score produced by the place
name disambiguation algorithm. Currently returns a placeholder value;
subject to change.
name 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.
admin1 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.")
type A text description of the geographic feature
type <U+2014> see http://www.geonames.org/ for a complete list. Subject to
change.
geometry.type Type of the geographical feature, e.g.
"Point".
longitude Longitude.
latitude Latitude.
reference1 Start (index of the first character in the place
reference) -- each reference to this place name found in the input
text is on one distinct line.
reference2 End (index of the first character after the place
reference) -- each reference to this place name found in the input
text is on one distinct line.
text_md5 MD5 hash of the text that was sent to the API.
To get an API key, you need to register at https://geoparser.io/pricing.html. With an hobbyist account, you can make up to 1,000 calls a month to the API. For ease of use, save your API key as an environment variable as described at https://stat545-ubc.github.io/bit003_api-key-env-var.html.
The package will conveniently look for your API key using
Sys.getenv("GEOPARSER_KEY") so if your API key is an environment
variable called "GEOPARSER_KEY" you don't need to input it manually.
Geoparser.io works best on complete sentences in English. 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. In R, you can use the
opencage package for
geocoding!
# NOT RUN {
geoparser_q(text_input = "I was born in Vannes but I live in Barcelona.")
geoparser_q(text_input = c("I was born in Vannes but I live in Barcelona.",
"France is the most beautiful place in the world."))
# }
Run the code above in your browser using DataLab