---
title: "Get started with Tampa Bay open data"
description: "Find a dataset, retrieve its records, work with spatial data, and trace its source."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with Tampa Bay open data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

`tampaBayOpenData` retrieves public ArcGIS data from six Tampa Bay publishers.
It includes 52 checked layers in an offline catalog and can search the
publishers' live portals. Retrieval returns a tibble or, with `sf` installed,
a spatial object.

The offline catalog examples below run during the vignette build. Live
discovery and retrieval examples are displayed but not run; try them in an
internet-connected R session.

## Find data

The checked catalog has stable package IDs and works offline:

```{r checked-catalog, eval=TRUE}
library(tampaBayOpenData)

tampaBayOpenData::tbod_list_portals()[, c("id", "publisher", "jurisdiction")]
tampaBayOpenData::tbod_search_datasets("park", source = "checked")[,
  c("id", "title", "jurisdiction", "validation_status")]
tampaBayOpenData::tbod_dataset_info("construction-permits")[
  c("title", "scope_note", "verified")]
```

`tbod_dataset_info()` reports a checked entry's source, terms, and scope.
To look beyond the catalog, search the live portals:

```{r live-discovery}
found <- tbod_search_datasets("housing", source = "live", portals = "city")
found[, c("id", "title", "publisher", "validation_status")]
```

The default catalog search scans all six live publishers and includes checked
entries. Set `portals` to narrow the live scan; matching checked entries still
appear. Set `jurisdiction` to filter both live and checked results. A `discovered`
result has not received the catalog's source checks; inspect its metadata and
reuse terms before analysis. The [discovery article](discovery.html) covers
filters, scan limits, and ArcGIS sources outside the bundled region.

## Retrieve records

Pass a checked ID, a discovered ID, or a one-row search result to
`tbod_get_dataset()`. If a checked ID is shared by multiple jurisdictions,
supply `jurisdiction` as well.

```{r retrieve}
permits <- tbod_get_dataset(
  "construction-permits",
  where = "PROJECTSTATUS IS NOT NULL",
  fields = c("RECORD_ID", "PROJECTSTATUS", "LASTUPDATE"),
  limit = 100
)
head(permits)
sort(table(permits$PROJECTSTATUS), decreasing = TRUE)
```

The counts describe the retrieved subset. Omit `limit` to retrieve all
matching rows. Passing a discovery row keeps its source information:

```{r discovered-retrieval}
if (nrow(found)) {
  housing <- tbod_get_dataset(found[1, ], limit = 100)
  tbod_provenance(housing)[c("publisher", "validation_status", "complete")]
}
```

Before retrieving a checked layer, the package compares its current fields,
geometry, and CRS with the bundled schema. Added fields warn; incompatible
changes stop retrieval. See `tbod_check_schema()` and the [retrieval
article](retrieval.html) for the full drift report.

## Work with spatial data

Install the optional `sf` package and request `spatial = TRUE` for an `sf`
result. `out_sr = 4326` asks the service for WGS 84 coordinates; without
`out_sr`, the client keeps the native CRS.

```{r spatial}
projects <- tbod_get_dataset("development-cases", spatial = TRUE,
                        out_sr = 4326)
sf::st_crs(projects)$epsg
```

The [retrieval article](retrieval.html) maps this layer and describes filters,
integrity checks, data types, and downloads.

## Trace the source

`tbod_provenance()` records the source, query, retrieval time, row counts,
and completeness. Save it separately before transformations that may discard
attributes.

```{r provenance}
source <- tbod_provenance(projects)
saveRDS(list(data = projects, provenance = source),
        "development-cases.rds")
```

The [coverage article](coverage.html) covers source limits, attribution, and
citation. A retrieved layer is not necessarily a complete historical record
or a legal boundary.