geoparser_q: Issue a geoparser query

In geoparser: Interface to the Geoparser.io API for Identifying and Disambiguating Places Mentioned in Text

Description

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.

Usage

geoparser_q(text_input, key = geoparser_key())

Arguments

text_input	A vector of strings, where each size must be smaller than 8 KB. See nchar(text_input, type = "bytes").
key	Your geoparser.io key.

Details

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!

Value

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 — 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.

References

Geoparser.io documentation

Examples

## 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."))

## End(Not run)

Example output

The API call failed, the error message is Error in curl::curl_fetch_memory(url, handle = handle): Couldn't resolve host name

$results
NULL

$properties
NULL

The API call failed, the error message is Error in curl::curl_fetch_memory(url, handle = handle): Couldn't resolve host name

The API call failed, the error message is Error in curl::curl_fetch_memory(url, handle = handle): Couldn't resolve host name

$results
NULL

$properties
NULL

geoparser documentation built on July 27, 2019, 1:02 a.m.