Skip to contents

Get data from an Airtable base and optionally convert to a sf object

Source: R/get_airtable_data.R
get_airtable_data.Rd

[Experimental] Get data from an Airtable base using the Airtable API, a development version of the rairtable package, and the httr2 package. If the base includes coordinate fields/columns, optionally convert the data to a simple feature object using sfext::df_to_sf() if geometry = TRUE.

Usage

get_airtable_data(
  base,
  table = NULL,
  view = NULL,
  record = deprecated(),
  fields = NULL,
  filter = NULL,
  sort = NULL,
  direction = "asc",
  desc = deprecated(),
  max_records = 100,
  per_page = NULL,
  cell_format = "json",
  tz = NULL,
  locale = NULL,
  fields_by_id = FALSE,
  offset = NULL,
  geometry = FALSE,
  location = NULL,
  dist = getOption("getdata.dist"),
  diag_ratio = getOption("getdata.diag_ratio"),
  unit = getOption("getdata.unit", "meter"),
  asp = getOption("getdata.asp"),
  crs = getOption("getdata.crs", 3857),
  coords = getOption("getdata.coords", c("lon", "lat")),
  from_crs = getOption("getdata.from_crs", 4326),
  remove_coords = TRUE,
  address = getOption("getdata.address", "address"),
  geo = FALSE,
  name_repair = janitor::make_clean_names,
  token = NULL,
  type = "AIRTABLE_TOKEN",
  resp_type = deprecated(),
  ...
)

get_airtable_metadata(
  base,
  table = NULL,
  token = NULL,
  type = "AIRTABLE_TOKEN",
  resp_type = "tables",
  fields = FALSE
)

Arguments

base

Airtable base id starting with with "app". Optional if url or airtable are supplied. If base is an Airtable url, the table and view are replaced based on the values parsed from the url. Required.

table

Airtable table id or name. If table is a table ID it is a string starting with "viw". Optional only if base is a url.

view

Airtable view ID. View ID values starts with "viw". Optional if require_view is FALSE.

record

Airtable record identifier, Default: NULL Superseded by rairtable::list_records() function.

fields

For get_airtable_metadata(), if TRUE, return the fields column from the data.frame with the Airtable response. If only one table is provided, fields are returned as a data frame. Ignored if table is NULL

filter

Placeholder for filterByFormula API parameter allowing use of SQL style queries to filter data. Not yet implemented.

sort

Field names to sort by. Defaults to NULL.

direction

A string ("asc" for ascending (default) or "desc" for descending) or character vector matching length of sort parameter. Ignored if sort is NULL.

desc

Deprecated. Sort results in descending order. Replaced by direction parameter.

max_records

Maximum number of records to return. Must be 100 or less.

per_page

Passed to page_size parameter of rairtable::list_records()

cell_format

Cell format for "Link to another record" fields. Defaults to "json" which returns a unique record ID. A "string" cell_format returns the displayed character string.

tz, locale

Time zone and locale, Defaults to NULL. If cell_format is "string", tz defaults to Sys.timezone() and locale defaults to Sys.getlocale("LC_TIME").

fields_by_id

If TRUE, use fields IDs for column names in returned records. If FALSE (default), use field names.

offset

Offset parameter, Default: NULL

geometry

If TRUE, convert data into a simple feature object. Defaults to FALSE.

location

sf object. If multiple areas are provided, they are unioned into a single sf object using sf::st_union()

dist

buffer distance in units. Optional.

diag_ratio

ratio of diagonal distance of area's bounding box used as buffer distance. e.g. if the diagonal distance is 3000 meters and the "diag_ratio = 0.1" a 300 meter will be used. Ignored when dist is provided.

unit

Units for buffer. Supported options include "meter", "foot", "kilometer", and "mile", "nautical mile" Common abbreviations (e.g. "km" instead of "kilometer") are also supported. Distance in units is converted to units matching GDAL units for x; defaults to "meter"

asp

Aspect ratio of width to height as a numeric value (e.g. 0.33) or character (e.g. "1:3"). If numeric, get_asp() returns the same value without modification.

crs

Cordinate reference system to return, Default: 4326 for sf_to_df() and NULL for df_to_sf().

coords

Coordinate columns for input data.frame or output sf object (if geometry is 'centroid' or 'point') Default: c("lon", "lat").

from_crs

For df_to_sf(), coordinate reference system used by coordinates or well known text in data frame.

remove_coords

For df_to_sf(), if TRUE, remove the coordinate columns after converting a data frame to simple feature object; defaults to FALSE.

address

Address column name passed to tidygeocoder::geocode() or tidygeocoder::geo

geo

If TRUE, use address_to_sf() to geocode address column; defaults to FALSE.

name_repair

One of "unique" (default), "universal", "check_unique", "unique_quiet", or "universal_quiet" passed to vctrs::vec_cbind(). See vctrs::vec_as_names for the meaning of these options.

token, type

API token and type, token defaults to NULL and type to "AIRTABLE_TOKEN" (same as get_access_token(type = "AIRTABLE_TOKEN")).

resp_type

Response type to return, Reprecated. Previously, set resp_type to "resp" to return the API response without any additional formatting or conversion.

...

Arguments passed on to rairtable::list_records

airtable

An airtable class object. Optional for read_airtable() if url is supplied. For list_records() and get_record(), support the airtable, url, or a base and table parameter.

airtable_id_col

Airtable record ID column name assigned to returned data frame. Defaults to NULL which is sets record ID column name to getOption("rairtable.id_col", "airtable_record_id"). For list_records() and get_record(), airtable_id_col is not used if metadata is NULL or does not include "id". The record ID column is dropped and converted to rownames if id_to_col is FALSE.

model

Optional. A table model from get_table_model(). If supplied, model is used to validate fields and sort parameters and to arrange columns to match the order of the table model.

.name_repair

One of "unique" (default), "universal", "check_unique", "unique_quiet", or "universal_quiet" passed to vctrs::vec_cbind(). See vctrs::vec_as_names for the meaning of these options.

tz,locale

Time zone and locale, Defaults to NULL. If cell_format is "string", tz defaults to Sys.timezone() and locale defaults to Sys.getlocale("LC_TIME").

page_size

Maximum number of records to return per page.

metadata

Record metadata columns to include with returned data frame. Options including "id", "createdTime", and "commentCount". Defaults to c("id", "createdTime"). If metadata is NULL, no additional fields are added to the returned data frame.

simplifyVector

Passed to httr2::req_body_json(). If FALSE, get_record() and list_records() both return named lists of records.

Details

This function an Airtable personal access token which you can create at https://airtable.com/create/tokens and save to your local environment with set_access_token(token = <YOUR_PERSONAL_ACCESS_TOKEN>, type = "AIRTABLE_TOKEN"). The function previously required an Airtable API key which you can set using set_access_token(token = <YOUR_API_KEY>, type = "AIRTABLE_API_KEY"). However, Airtable is in the process of deprecating user API keys.

get_airtable_data() requires a scope that includes data.records:read and get_airtable_metadata() a scope including schema.bases:read.

As of May 2023, this function depends on the dev branch of my fork of the rairtable package. I expect this dependency to switch back to the rairtable package when the fork is merged.

Learn more about the Airtable API https://airtable.com/developers/web/api/introduction