R/rgeocodio-package.R

In hrbrmstr/rgeocodio: Tools to Work with the 'Geocodio' 'API'

#' Tools to Work with the [Geocodio](https://geocod.io) 'API'
#'
#' An R interface to forward & reverse geocoding (with many extra possible return fields)
#' lookups using the Geocodio API.
#'
#' NOTE: You need an [API key](https://dash.geocod.io/) to use this package. The functions
#' in this package look for this API key in the `GEOCODIO_API_KEY` environment variable.
#'
#' It is highly recommended that you store this API key in your `~/.Renviron` file.
#'
#' @section Geocoding:
#'
#' Geocoding (also known as forward geocoding) allows you to convert one or more addresses
#' into geographic coordinates (i.e. latitude and longitude). Geocoding will also parse the
#' address and append additional information (e.g. if you specify a zip code, Geocodio will
#' return the city and state corresponding the zip code as well).
#'
#' Geocodio supports geocoding of addresses, cities and zip codes in various formats.
#'
#' You can either geocode a single address at a time or collect multiple addresses in
#' batches in order to geocode up to 10,000 addresses at the time.
#'
#' Reverse geocoding is the process of turning geographic coordinates (i.e. latitude and
#' longitude) into a human-readable address.
#'
#' Geocodio will find matching street(s) and determine the correct house number based on
#' the location. Note that Geocodio does not guarantee to return a valid house number; it
#' is our closest approximation.
#'
#' As with forward geocoding, you can either geocode a single set of coordinates at the
#' time or collect multiple coordinates in batches and reverse geocode up to 10,000
#' coordinates at the time.
#'
#' @section Accuracy:
#'
#' Each geocoded result is returned with an accuracy score, which is a decimal number
#' ranging from 0.00 to 1.00. This score is generated by the internal Geocodio engine
#' based on how accurate the result is believed to be. The higher the score the better
#' the result. Results are always returned ordered by accuracy score.
#'
#' For example, if against all odds an address simply can’t be found — instead of
#' returning no results, Geocodio will return a geocoded point based on the zip code or
#' city but with a much lower accuracy score and accuracy type set to “place”.
#'
#' Generally, accuracy scores that are larger than or equal to 0.8 are usually helpful,
#' whereas results with lower accuracy scores might be very rough matches.
#'
#' An accuracy type is also returned with all results. The accuracy types are different
#' for forward and reverse geocoding results.
#'
#' We recommend using a combination of the accuracy score and accuracy type to evaluate
#' and filter the returned results.
#'
#' @section AddresFormats:
#'
#' Geocodio supports geocoding the following entities:
#'
#' - Streets with or without house numbers (requires a city or a zip in conjuction)
#' - Intersections
#' - Cities
#' - Zip codes
#' - States
#'
#' If a city is provided without a state, Geocodio will automatically guess and add the
#' state based on what it most likely might be. Geocodio also understands shorthands for
#' both streets and cities, e.g. NYC, SF, etc. are acceptable city names.
#'
#' **You can also geocode intersections.** Just specify the two streets that you want to
#' geocode in your query.
#'
#' @section Fields:
#'
#' NOTE: Specifying additional return fields will deplete API credits faster.
#'
#' All forward and reverse geocoding functions take an optional `fields` parameter
#' which enables retrieving extra information for a location.
#'
#' **Congressional Districts**
#'
#' You can retrieve the congressional district for an address or coordinate using
#' `cd`, `cd113`, `cd114`, or `cd115` in the fields query parameter. `cd` will always return
#' the congressional district for the current progress while e.g. `cd113` will continue
#' to show the congressional district for the `113th` congress.
#'
#' The field returns the full name of the congressional district, the district number
#' the congress number and the range of years the congress are covering.
#'
#' **State Legislative Districts**
#'
#' You can retrieve the state legislative districts for an address or coordinate using
#' `stateleg` in the fields query parameter.
#'
#' The field will return both the house and senate state legislative district (also known
#' as lower and upper) with the full name and district number for each. For areas with a
#' unicameral legislature (such as Washington DC or Nebraska), only the senate key is
#' returned.
#'
#' **School Districts**
#'
#' You can retrieve the school districts for an address or coordinate using `school` in the
#' fields query parameter.
#'
#' The field will return either a unified school district or separate elementary and
#' secondary fields depending on the area. Each school district is returned with its
#' full name, the LEA (Local Education Agency) code as well as the grades supported.
#' Kindergarden is abbreviated as KG and Pre-kindergarten is abbreviated as PK.
#'
#' **Census Block/Tract & FIPS codes**
#'
#' See [the official documentation](https://geocod.io/docs/#census-block-tract-amp-fips-codes).
#'
#' **Timezone**
#'
#' See [the official documentation](https://geocod.io/docs/#timezone).
#'
#' @md
#' @encoding UTF-8
#' @name rgeocodio
#' @docType package
#' @author Bob Rudis (bob@@rud.is)
#' @import purrr httr
#' @importFrom jsonlite fromJSON
#' @importFrom tibble as_tibble
NULL