From 41fcc6268b637eecf28f4e163cbedd0741d55154 Mon Sep 17 00:00:00 2001 From: Josiah Parry Date: Thu, 6 Jun 2024 10:28:52 -0400 Subject: [PATCH] add places --- .../places/overview/execute-results/html.json | 15 +++ _quarto.yml | 2 + docs/places/overview.qmd | 97 +++++++++++++++++++ 3 files changed, 114 insertions(+) create mode 100644 _freeze/docs/places/overview/execute-results/html.json create mode 100644 docs/places/overview.qmd diff --git a/_freeze/docs/places/overview/execute-results/html.json b/_freeze/docs/places/overview/execute-results/html.json new file mode 100644 index 0000000..8d6cf8a --- /dev/null +++ b/_freeze/docs/places/overview/execute-results/html.json @@ -0,0 +1,15 @@ +{ + "hash": "c036e3b3539db1f30e11d4de7b23e904", + "result": { + "engine": "knitr", + "markdown": "---\ntitle: Overview\n---\n\n\n\n`{arcgisplaces}` is an R package to interface with [ArcGIS Places Service](https://developers.arcgis.com/rest/places/).\n\n> The places service is a ready-to-use location service that can search for businesses and geographic locations around the world. It allows you to find, locate, and discover detailed information about each place.\n\nIn order to use `{arcgisplaces}` you will need an ArcGIS Developers account. [Get started here.](https://developers.arcgis.com/documentation/mapping-apis-and-services/get-started/)\n\n## Installation\n\n`{arcgisplaces}` can be installed directly from CRAN using \n\n```r\ninstall.packages(\"arcgisplaces\")\n```\n\n## Usage\n\nThe Places service enables you to find points of interest (POI) based on a location or a bounding box as well as filter your results based on a category or search text. \n\nFinding places: \n\n- `near_point()`: search for places near a location.\n- `within_extent()`: search for places within an extent.\n- `place_details()`: get detailed information about the places returned from `near_point()` or `within_extent()`. \n - Note: see `fields` for the possible attributes to return for place details.\n\nUnderstanding categories: \n\n- `categories()`: find categories by name or ID.\n- `category_details()`: get detailed information about the categories returned from `categories()`.\n\n- Find place attributes such as name, address, description, opening hours, price ratings, user ratings, and social links.\n\n\n## Examples\n\n\n\n\n\n`arcgisutils` is needed for authentication. The Places API supports either using an API key via `auth_key()` or one generated via OAuth2 using either `auth_client()` or `auth_code()`. See [API documentation](https://developers.arcgis.com/rest/places/#authentication) for more.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nlibrary(arcgisutils)\nlibrary(arcgisplaces)\n\n# Authenticate with a Developer Account API Key\ntoken <- auth_key()\nset_arc_token(token)\n```\n:::\n\n\n## Place search \n\nYou can **search for places near a location** with `near_point()`.\n\n\n::: {.cell}\n\n```{.r .cell-code}\ncoffee <- near_point(x = -122.334, y = 47.655, search_text = \"Coffee\")\ncoffee\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\nSimple feature collection with 8 features and 5 fields\nGeometry type: POINT\nDimension: XY\nBounding box: xmin: -1122.334 ymin: -952.345 xmax: 877.666 ymax: 1047.655\nGeodetic CRS: WGS 84\n place_id name\n1 f6059fc575735b5e3f558c96ab69e6f6 Irwin's Neighborhood Bakery and Cafe\n2 88a10ccf031f02ef2697591f72e1e169 Fuel Coffee\n3 5cc2d40bf37bff287382057c5fdf4978 Young Tea\n4 a8c6da1aa0d08fe96e5d80d0f3b3de03 Friday Afternoon\n5 906da2fe5164619199a2f2ba9c99a650 Starbucks\n6 957c39de6e0a0eb8afeb841d456c72fc Mosaic Coffeehouse\n7 4bdfa82268e67a698d0b8ea3d2df3853 A Muddy Cup\n8 090286b411e3337850ec8fff6b43569b The Bounty\n distance categories icon geometry\n1 97.0 c(\"13002.... POINT (-122.3328 47.65539)\n2 723.8 c(\"13035.... POINT (-122.3369 47.66122)\n3 727.6 c(\"13033.... POINT (-122.3331 47.66152)\n4 740.8 c(\"13036.... POINT (-122.342 47.65895)\n5 767.3 13035, C.... POINT (-122.3361 47.66175)\n6 774.0 c(\"13034.... POINT (-122.3276 47.66048)\n7 964.2 c(\"13035.... POINT (-122.3255 47.66149)\n8 976.2 c(\"13034.... POINT (-122.3426 47.66162)\n```\n\n\n:::\n:::\n\n\nLocations are returned as an sf object with the place ID, the place name, distance from the search point, a character vector of categories. \n\n\n::: callout-tip\n\n`arcgisplaces` will return an sf object, but the sf package is not required to work with the package. The `sf` print method will not be used unless the package is loaded. If package size is a consideration—i.e. deploying an app in a Docker container—consider using `wk` or `rsgeo`.\n\n:::\n\nDetails for the places can be fetched using `place_details()`. The possible fields are [documented online](https://developers.arcgis.com/rest/places/place-id-get/#requestedfields) as well as contained in the exported vector `fields`. Because pricing is dependent upon which fields are requested, it is a required argument. \n\nTo get the add `requested_fields = \"hours\"`. Note, that the other possible fields will still be present in the result, but completely empty. \n\n\n::: {.cell}\n\n```{.r .cell-code}\ndetails <- place_details(\n coffee$place_id,\n requested_fields = \"rating\"\n)\n\ndetails[c(\"price\", \"user\")]\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\nSimple feature collection with 8 features and 2 fields\nGeometry type: POINT\nDimension: XY\nBounding box: xmin: Inf ymin: Inf xmax: -Inf ymax: -Inf\nGeodetic CRS: WGS 84\n price user location\n1 Cheap 4.1 POINT EMPTY\n2 Cheap 3.9 POINT EMPTY\n3 NA POINT EMPTY\n4 Moderate NA POINT EMPTY\n5 Cheap 3.4 POINT EMPTY\n6 Cheap 3.0 POINT EMPTY\n7 Cheap 4.0 POINT EMPTY\n8 NA POINT EMPTY\n```\n\n\n:::\n:::\n\n\nOr, you can search for places within a bounding box using `within_extent()`. This could be quite handy for searching within current map bounds, for example. \n\n\n::: {.cell}\n\n```{.r .cell-code}\nbakeries <- within_extent(\n -70.356, 43.588, -70.176, 43.7182,\n category_id = \"13002\"\n)\n\nbakeries[c(\"name\")]\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\nSimple feature collection with 24 features and 1 field\nGeometry type: POINT\nDimension: XY\nBounding box: xmin: -70.356 ymin: 43.588 xmax: -70.176 ymax: 43.7182\nGeodetic CRS: WGS 84\nFirst 10 features:\n name geometry\n1 Panera Bread POINT (-70.32966 43.67791)\n2 Crumbl Cookies POINT (-70.33067 43.67675)\n3 Electric Bike Cafe POINT (-70.2864 43.63655)\n4 BenReuben’s Knishery POINT (-70.25299 43.63748)\n5 Two Fat Cats Bakery POINT (-70.26101 43.6327)\n6 Auntie Anne's POINT (-70.33517 43.63372)\n7 Lolli and Pops POINT (-70.33512 43.63377)\n8 Panera Bread POINT (-70.3303 43.6367)\n9 Cookie Jar Pastry Shop POINT (-70.22644 43.63367)\n10 Bake Maine Pottery Cafe POINT (-70.25334 43.66708)\n```\n\n\n:::\n:::", + "supporting": [], + "filters": [ + "rmarkdown/pagebreak.lua" + ], + "includes": {}, + "engineDependencies": {}, + "preserve": {}, + "postProcess": true + } +} \ No newline at end of file diff --git a/_quarto.yml b/_quarto.yml index ba0f0e9..daa4ab2 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -57,6 +57,8 @@ website: - href: docs/geocode/reverse-geocoding.qmd text: "Reverse Geocoding" - section: Places + contents: + - docs/places/overview.qmd # - section: ArcGIS Pro diff --git a/docs/places/overview.qmd b/docs/places/overview.qmd new file mode 100644 index 0000000..c162d8f --- /dev/null +++ b/docs/places/overview.qmd @@ -0,0 +1,97 @@ +--- +title: Overview +--- + + +`{arcgisplaces}` is an R package to interface with [ArcGIS Places Service](https://developers.arcgis.com/rest/places/). + +> The places service is a ready-to-use location service that can search for businesses and geographic locations around the world. It allows you to find, locate, and discover detailed information about each place. + +In order to use `{arcgisplaces}` you will need an ArcGIS Developers account. [Get started here.](https://developers.arcgis.com/documentation/mapping-apis-and-services/get-started/) + +## Installation + +`{arcgisplaces}` can be installed directly from CRAN using + +```r +install.packages("arcgisplaces") +``` + +## Usage + +The Places service enables you to find points of interest (POI) based on a location or a bounding box as well as filter your results based on a category or search text. + +Finding places: + +- `near_point()`: search for places near a location. +- `within_extent()`: search for places within an extent. +- `place_details()`: get detailed information about the places returned from `near_point()` or `within_extent()`. + - Note: see `fields` for the possible attributes to return for place details. + +Understanding categories: + +- `categories()`: find categories by name or ID. +- `category_details()`: get detailed information about the categories returned from `categories()`. + +- Find place attributes such as name, address, description, opening hours, price ratings, user ratings, and social links. + + +## Examples + +```{r include = FALSE} +library(sf) +library(pillar) +``` + +`arcgisutils` is needed for authentication. The Places API supports either using an API key via `auth_key()` or one generated via OAuth2 using either `auth_client()` or `auth_code()`. See [API documentation](https://developers.arcgis.com/rest/places/#authentication) for more. + +```{r message=FALSE} +library(arcgisutils) +library(arcgisplaces) + +# Authenticate with a Developer Account API Key +token <- auth_key() +set_arc_token(token) +``` + +## Place search + +You can **search for places near a location** with `near_point()`. + +```{r} +coffee <- near_point(x = -122.334, y = 47.655, search_text = "Coffee") +coffee +``` + +Locations are returned as an sf object with the place ID, the place name, distance from the search point, a character vector of categories. + + +::: callout-tip + +`arcgisplaces` will return an sf object, but the sf package is not required to work with the package. The `sf` print method will not be used unless the package is loaded. If package size is a consideration—i.e. deploying an app in a Docker container—consider using `wk` or `rsgeo`. + +::: + +Details for the places can be fetched using `place_details()`. The possible fields are [documented online](https://developers.arcgis.com/rest/places/place-id-get/#requestedfields) as well as contained in the exported vector `fields`. Because pricing is dependent upon which fields are requested, it is a required argument. + +To get the add `requested_fields = "hours"`. Note, that the other possible fields will still be present in the result, but completely empty. + +```{r message=FALSE} +details <- place_details( + coffee$place_id, + requested_fields = "rating" +) + +details[c("price", "user")] +``` + +Or, you can search for places within a bounding box using `within_extent()`. This could be quite handy for searching within current map bounds, for example. + +```{r} +bakeries <- within_extent( + -70.356, 43.588, -70.176, 43.7182, + category_id = "13002" +) + +bakeries[c("name")] +``` \ No newline at end of file