From fb4253b0472bf8d1b88cda787d44cf35bf8953f3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 01:33:22 +0000 Subject: [PATCH 1/3] Initial plan From 584303e7cb83a4e9ff2a1e53f9c3577b31327d37 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 01:36:16 +0000 Subject: [PATCH 2/3] Add search endpoint documentation and route Co-authored-by: brucecrevensten <525049+brucecrevensten@users.noreply.github.com> --- routes/vectordata.py | 5 + templates/documentation/search.html | 475 ++++++++++++++++++++++++++++ 2 files changed, 480 insertions(+) create mode 100644 templates/documentation/search.html diff --git a/routes/vectordata.py b/routes/vectordata.py index 7237de30..2b1a0e59 100644 --- a/routes/vectordata.py +++ b/routes/vectordata.py @@ -51,6 +51,11 @@ extent_filtered_communities[extent] = filtered +@routes.route("/search/") +def search_about(): + return render_template("/documentation/search.html") + + @routes.route("/places/search//") def find_via_gs(lat, lon): """ diff --git a/templates/documentation/search.html b/templates/documentation/search.html new file mode 100644 index 00000000..9dba1d0d --- /dev/null +++ b/templates/documentation/search.html @@ -0,0 +1,475 @@ +{% extends 'base.html' %} {% block content %} +

Places Search

+ +

+ The Places Search endpoints provide geographic lookup and discovery services for + communities and polygon areas within Alaska and Arctic regions. These endpoints + allow you to find nearby places by coordinates, search for communities by name, + and retrieve detailed geographic metadata for analysis and visualization. +

+ +

Service Endpoints

+ +

Geographic Search by Coordinates

+ +

+ Search for nearby communities and polygon areas using latitude and longitude + coordinates. This endpoint returns all geographic features within a proximity + threshold, including communities, HUC watersheds, protected areas, and various + administrative boundaries. +

+ + + + + + + + + + + + + + + + + + +
EndpointExample URL
+ Geographic search for all nearby communities and areas + + /places/search/64.8377/-147.7164 +
+ Geographic search filtered by community tags + + /places/search/64.8377/-147.7164?tags=park,airport +
+ +
Geographic Search Parameters
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeRequiredDescription
latFloatYes + Latitude coordinate in decimal degrees. Must be within the bounding box + of the data service's area of interest. +
lonFloatYes + Longitude coordinate in decimal degrees. Must be within the bounding box + of the data service's area of interest. +
tagsStringNo + Optional comma-separated list of tags to filter communities. Only + communities with at least one matching tag will be returned. Examples: + park, airport, school. +
+ +
Geographic Search Output
+ +

+ Data are returned as JSON with separate keys for communities and each type of + polygon area. The response includes detailed metadata and GeoJSON geometry + for each feature, along with a bounding box encompassing all returned features. +

+ +
{
+  "communities": {
+    "0": {
+      "name": "Fairbanks",
+      "alt_name": "Fairbanks, Alaska",
+      "id": "AK124",
+      "region": "Alaska",
+      "country": "US",
+      "type": "community",
+      "latitude": "64.8377",
+      "longitude": "-147.7164",
+      "is_coastal": "f",
+      "ocean_lat1": null,
+      "ocean_lon1": null
+    }
+  },
+  "hucs_near": {
+    "0": {
+      "geojson": {
+        "type": "MultiPolygon",
+        "coordinates": [...]
+      },
+      "id": "19040506",
+      "name": "Tanana Flats",
+      "type": "huc"
+    }
+  },
+  "protected_areas_near": {
+    "0": {
+      "geojson": {
+        "type": "MultiPolygon",
+        "coordinates": [...]
+      },
+      "id": "141",
+      "name": "Creamer's Field Migratory Waterfowl Refuge",
+      "type": "protected_area"
+    }
+  },
+  "ak_boros_near": {},
+  "ak_censusarea_near": {},
+  "climate_divisions_near": {},
+  "corporations_near": {},
+  "ethnolinguistic_regions_near": {},
+  "fire_management_units_near": {},
+  "yt_fire_districts_near": {},
+  "game_management_units_near": {},
+  "yt_game_management_subzones_near": {},
+  "ca_first_nations_near": {},
+  "yt_watersheds_near": {},
+  "ecoregions_near": {},
+  "total_bounds": {
+    "xmin": -147.85,
+    "ymin": 64.75,
+    "xmax": -147.65,
+    "ymax": 64.92
+  }
+}
+
+ +
Area Types in Geographic Search Output
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescription
communitiesNamed communities, villages, towns, and cities
hucs_nearHydrologic Unit Code (HUC) watersheds
protected_areas_nearNational parks, wildlife refuges, and other protected areas
ak_boros_nearAlaska boroughs (county equivalents)
ak_censusarea_nearAlaska census areas
climate_divisions_nearNOAA climate divisions
corporations_nearAlaska Native Regional Corporations
ethnolinguistic_regions_nearIndigenous language and cultural regions
fire_management_units_nearFire management zones
yt_fire_districts_nearYukon Territory fire districts
game_management_units_nearWildlife game management units
yt_game_management_subzones_nearYukon Territory game management subzones
ca_first_nations_nearCanadian First Nations territories
yt_watersheds_nearYukon Territory watersheds
ecoregions_nearEcological regions
total_boundsBounding box (xmin, ymin, xmax, ymax) encompassing all returned features
+ +

Community Search by Name

+ +

+ Search for communities by name using fuzzy string matching. This endpoint + supports filtering by geographic extent and uses the Jaro-Winkler algorithm + to match community names, making it robust to spelling variations and partial + matches. +

+ + + + + + + + + + + + + + + + + + + + + + +
EndpointExample URL
+ Search all communities by name substring + + /places/search/communities?substring=fair +
+ Search communities within Alaska extent + + /places/search/communities?extent=alaska&substring=anch +
+ Get all communities within a specific extent + + /places/search/communities?extent=elevation +
+ +
Community Search Parameters
+ + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeRequiredDescription
extentStringNo + Geographic region filter. Valid values: alaska, + blockyAlaska, elevation, mizukami, + slie. If omitted, searches across all available communities. +
substringStringNo + Search term to match against community names and alternate names. Uses + fuzzy matching with the Jaro-Winkler algorithm (minimum similarity + threshold of 0.8). Results are sorted by match quality. Case-insensitive. +
+ +
Community Search Output
+ +

+ Data are returned as a JSON array of community objects, ordered by match + quality when using substring search. Each community includes its name, location, + and metadata. +

+ +
[
+  {
+    "name": "Fairbanks",
+    "alt_name": "Fairbanks, Alaska",
+    "id": "AK124",
+    "region": "Alaska",
+    "country": "US",
+    "type": "community",
+    "latitude": "64.8377",
+    "longitude": "-147.7164",
+    "tags": "city,airport",
+    "is_coastal": "f",
+    "ocean_lat1": null,
+    "ocean_lon1": null
+  },
+  {
+    "name": "North Pole",
+    "alt_name": "North Pole, Alaska",
+    "id": "AK234",
+    "region": "Alaska",
+    "country": "US",
+    "type": "community",
+    "latitude": "64.7511",
+    "longitude": "-147.3494",
+    "tags": "city",
+    "is_coastal": "f",
+    "ocean_lat1": null,
+    "ocean_lon1": null
+  }
+]
+
+ +
Community Properties
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
nameStringPrimary name of the community
alt_nameStringAlternate or official name of the community
idStringUnique identifier for the community
regionStringGeographic region (e.g., "Alaska", "Yukon Territory")
countryStringCountry code (e.g., "US", "CA")
typeStringFeature type (always "community" for this endpoint)
latitudeStringLatitude coordinate in decimal degrees
longitudeStringLongitude coordinate in decimal degrees
tagsString + Comma-separated list of tags describing community features (e.g., + "city,airport,school"). Note: Tags are removed from output when using + tag filtering in the geographic search endpoint. +
is_coastalStringBoolean flag ("t" or "f") indicating if community is coastal
ocean_lat1String/NullLatitude of nearest ocean point (for coastal communities)
ocean_lon1String/NullLongitude of nearest ocean point (for coastal communities)
+ +

Use Cases

+ + + +

Related Resources

+ +

+ For more information about the types of places available in this API, see the + Places documentation. +

+ +{% endblock %} From bb2fdaf546e2efe1550334a9335982aee13653f7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 01:39:41 +0000 Subject: [PATCH 3/3] Add test for search documentation endpoint Co-authored-by: brucecrevensten <525049+brucecrevensten@users.noreply.github.com> --- tests/test_search_documentation.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 tests/test_search_documentation.py diff --git a/tests/test_search_documentation.py b/tests/test_search_documentation.py new file mode 100644 index 00000000..8e291ac9 --- /dev/null +++ b/tests/test_search_documentation.py @@ -0,0 +1,14 @@ +def test_search_documentation(client): + """ + Tests the /search/ documentation endpoint to ensure it returns a 200 status + and contains the expected documentation content. + """ + response = client.get("/search/") + assert response.status_code == 200 + + # Check that the response contains expected documentation content + html = response.data.decode("utf-8") + assert "Places Search" in html + assert "/places/search/" in html + assert "Geographic Search by Coordinates" in html + assert "Community Search by Name" in html