improve documentation for crime API

R/crime.R

@@ -10,7 +10,21 @@
 #'
 #' @note The API will return a 400 status code in response to a GET request longer than 4094 characters. For submitting particularly complex poly parameters, consider using POST instead.
 #'
-#' @return a tibble
+#' @return a tibble with the columns:
+#' \itemize{
+#'   \item category: Category of the crime (https://data.police.uk/docs/method/crime-street/)
+#'   \item persistent_id: 64-character unique identifier for that crime. (This is different to the existing 'id' attribute, which is not guaranteed to always stay the same for each crime.)
+#'   \item date: Date of the crime YYYY-MM
+#'   \item latitude: Latitude
+#'   \item longitude: Longitude
+#'   \item street_id: Unique identifier for the street
+#'   \item street_name: Name of the location. This is only an approximation of where the crime happened
+#'   \item context: Extra information about the crime (if applicable)
+#'   \item id: ID of the crime. This ID only relates to the API, it is NOT a police identifier
+#'   \item location_type: The type of the location. Either Force or BTP: Force indicates a normal police force location; BTP indicates a British Transport Police location. BTP locations fall within normal police force boundaries.
+#'   \item location_subtype: For BTP locations, the type of location at which this crime was recorded.
+#'   \item outcome_status: The category and date of the latest recorded outcome for the crime
+#' }
 #'
 #' @note more documentation here: https://data.police.uk/docs/method/crime-street/
 #'
@@ -21,15 +35,15 @@ ukp_crime_street_point <- function(lat,
                              date = NULL,
                              ...){
 
-  # lat = 52.629729
-  # lng = -1.131592
+  lat = 52.629729
+  lng = -1.131592
 
   # transforms this particular JSON list structure into a tibble
   unlist_crime_df <- function(result_content){
 
+    # result_content <- result$content[[1]]
     result_unlist <- unlist(result_content)
-
-    result_df <- as.data.frame(result_unlist)
+    result_df <- as.data.frame(result_unlist, stringsAsFactors = FALSE)
     result_df <- dplyr::mutate(result_df,
                                variables = rownames(result_df))
     result_df <- dplyr::select(result_df,
@@ -40,7 +54,7 @@ ukp_crime_street_point <- function(lat,
                                value = "result_unlist")
     result_df <- tibble::as_tibble(result_df)
 
-    result_df
+    return(result_df)
 
   }
 
@@ -68,16 +82,36 @@ ukp_crime_street_point <- function(lat,
   extract_result <- purrr::map_df(.x = result$content,
                                   .f = unlist_crime_df)
 
-  final_result <-
-  dplyr::rename(extract_result,
+  # rename the data
+  extract_result <- dplyr::rename(extract_result,
                 latitude = location.latitude,
                 longitude = location.longitude,
                 street_id = location.street.id,
                 street_name = location.street.name,
                 date = month,
-                outcome_category = outcome_status.category,
+                outcome_status = outcome_status.category,
                 outcome_date = outcome_status.date)
 
+
+  final_result <- dplyr::mutate(extract_result,
+                                latitude = as.numeric(latitude),
+                                longitude = as.numeric(longitude))
+
+  final_result <- dplyr::select(final_result,
+                                category,
+                                persistent_id,
+                                date,
+                                latitude,
+                                longitude,
+                                street_id,
+                                street_name,
+                                context,
+                                id,
+                                location_type,
+                                location_subtype,
+                                outcome_status,
+                                category)
+
   return(final_result)
 
 }

R/forces.R

@@ -7,7 +7,7 @@
 #' ukp_forces
 #'
 #' List of forces
-#' @return table with columns id, and name. id is a	Unique force identifier, name is a	Force name.
+# #' @return table with columns id, and name. id is a	Unique force identifier, name is a	Force name.
 #'
 #'
 #' Specific force

tests/testthat/test_crime.R

@@ -14,6 +14,7 @@
 #                        "persistent_id",
 #                        "outcome_category",
 #                        "outcome_date")
+# c("category", "persistent_id", "not", "date", "latitude", "longitude", "street_id", "street_name", "context", "id", "location_type", "es", "location_subtype", "outcome_status")
 #
 # test_crime <- ukp_crime_street_point(lat = 52.629729,
 #                                      lng = -1.131592)