Geospatial Metadata Extraction Prompt Template

This prompt is designed for platform engineers building hybrid retrieval systems where vector similarity search alone cannot satisfy spatial constraints. The core job-to-be-done is translating a user's natural language geographic expression—such as 'apartments near downtown Chicago' or 'conference venues within 50 miles of San Francisco'—into a structured, machine-readable filter object. This object can then be passed directly to a geospatial search backend like Elasticsearch, PostGIS, or a custom API. The ideal user is an engineering lead or developer who already has a geocoding service and a search index with latitude/longitude fields, and now needs a reliable extraction layer between the user's query and the database.

You should use this prompt when your application needs to parse geographic intent from free-text queries and convert it into actionable filter clauses. This includes handling place names ('near Central Park'), coordinate pairs ('around 37.7749, -122.4194'), radius expressions ('within 10 km of the Eiffel Tower'), bounding boxes, and ambiguous location references like 'downtown' or 'the Bay Area'. The prompt is not a geocoder; it does not resolve place names to coordinates. It extracts the intent and structure, leaving coordinate resolution to a dedicated geocoding service in your application harness. Pairing this prompt with a geocoder like Mapbox, Google Maps, or Nominatim is a required architectural pattern, not an optional enhancement.

Do not use this prompt when you need precise coordinate lookups, when the user's query contains no geographic signal, or when your search index lacks geospatial query capabilities. It is also insufficient for real-time navigation, routing, or any use case requiring sub-meter precision. The prompt excels at structured extraction but will fail silently or produce low-confidence output when given purely metaphorical location language ('the center of the debate') or references that require deep cultural knowledge to resolve. Always validate the output against a known schema and implement a confidence threshold below which the filter is discarded or flagged for human review. For high-stakes applications like emergency services or legal compliance, human approval must be a gating step before any extracted filter reaches the search backend.

This prompt template converts a user's natural language query into a structured geospatial filter object. It is designed for location-aware search and RAG applications where vector similarity alone cannot enforce geographic constraints. The template uses square-bracket placeholders for all dynamic inputs—replace these at runtime with your application's values. The output is a strict JSON schema that downstream systems can parse into database WHERE clauses, Elasticsearch geo-queries, or vector DB metadata filters.

textCopy
You are a geospatial metadata extraction system. Your job is to read a user query and extract any geographic constraints into a structured JSON object. Do not answer the query. Only extract location metadata.

## Input
User Query: [USER_QUERY]

## Context
- Current date and time: [CURRENT_DATETIME]
- User's approximate location if known: [USER_LOCATION]
- Known place catalog (name, canonical_name, centroid_lat, centroid_lon, radius_km, admin_hierarchy): [PLACE_CATALOG]
- Default search radius in kilometers when not specified: [DEFAULT_RADIUS_KM]

## Output Schema
Return a single JSON object with these fields:
- "locations": array of objects, each with:
  - "place_name": string (canonical name from catalog if matched, otherwise the extracted name)
  - "place_type": string (one of: "point", "city", "region", "country", "postal_code", "landmark", "custom_area")
  - "geometry": object with "type" ("Point" or "Polygon"), "coordinates" (GeoJSON coordinate array), and "radius_km" (number, null if Polygon)
  - "matched_catalog_entry": string or null (canonical name if found in place catalog, null if not)
  - "confidence": number between 0.0 and 1.0
- "spatial_operator": string (one of: "within", "near", "outside", "intersects")
- "ambiguous_locations": array of strings (place names that could not be disambiguated)
- "no_location_detected": boolean (true if no geographic constraint was found)

## Constraints
1. If the user mentions a place in the catalog, use the catalog's canonical name, centroid, and radius.
2. If a place is not in the catalog, estimate coordinates conservatively and set confidence below 0.5.
3. For proximity queries ("near", "around", "within X km of"), set spatial_operator to "near" and use the radius from the query or the default.
4. For containment queries ("in", "inside", "within" a named area), set spatial_operator to "within".
5. For exclusion queries ("outside", "not in", "excluding"), set spatial_operator to "outside".
6. Resolve relative location expressions ("near me", "nearby", "local") using the provided user location.
7. If a place name is ambiguous (e.g., "Springfield"), list it in ambiguous_locations and do not guess.
8. If no geographic constraint is detected, set no_location_detected to true and locations to an empty array.
9. Never invent coordinates for real places. If uncertain, set confidence low and flag as ambiguous.

## Examples
Query: "apartments in downtown Chicago within 2 miles"
Output: {"locations":[{"place_name":"Chicago","place_type":"city","geometry":{"type":"Point","coordinates":[-87.6298,41.8781],"radius_km":3.22},"matched_catalog_entry":"Chicago","confidence":0.95}],"spatial_operator":"near","ambiguous_locations":[],"no_location_detected":false}

Query: "best pizza places"
Output: {"locations":[],"spatial_operator":"within","ambiguous_locations":[],"no_location_detected":true}

Query: "hotels outside Paris city center"
Output: {"locations":[{"place_name":"Paris","place_type":"city","geometry":{"type":"Point","coordinates":[2.3522,48.8566],"radius_km":5.0},"matched_catalog_entry":"Paris","confidence":0.9}],"spatial_operator":"outside","ambiguous_locations":[],"no_location_detected":false}

## Risk Level
[RISK_LEVEL]

If RISK_LEVEL is "high", do not estimate coordinates for uncatalogued places. Set confidence to 0 and add to ambiguous_locations.

To adapt this template for production, replace the placeholders with runtime values from your application context. The [PLACE_CATALOG] should be a pre-loaded list of known places with canonical names and coordinates—this is your grounding source and prevents the model from hallucinating locations. The [RISK_LEVEL] parameter lets you toggle between permissive extraction (low-risk internal analytics) and strict extraction (high-risk applications where wrong coordinates cause real harm). After extraction, always validate the output JSON against the schema before passing it to your search backend. If ambiguous_locations is non-empty or confidence is below your threshold, route the query for human clarification or fall back to a non-geospatial search.

This prompt is not a standalone geocoder. It extracts structured geographic constraints from natural language text, producing a JSON object with place names, coordinate pairs, radius expressions, and ambiguity flags. The output must be validated against a geocoding service before it becomes a usable spatial filter in your search backend. Treat the LLM output as a parsing and normalization layer, not a source of truth for coordinates.

Wire the prompt as a pre-retrieval step in your RAG or search pipeline. After extraction, pass the place_name fields to a geocoding API (Mapbox, Google, Nominatim) to resolve coordinates and bounding boxes. For radius_meters and proximity expressions, validate that the resolved geometry matches the user's likely intent—a query for 'near downtown Denver' should not resolve to the entire Denver metro area. Implement a validation harness that checks: (1) all extracted place names resolve to valid geocodes, (2) coordinate pairs fall within expected bounds for the mentioned region, (3) radius values are positive and within configurable maximums (e.g., 100 km for 'nearby' queries), and (4) ambiguity scores above a threshold trigger a clarification request to the user rather than a guess. Log extraction confidence alongside resolved geometries for debugging.

For model choice, a fast instruction-tuned model like GPT-4o-mini, Claude 3.5 Haiku, or a fine-tuned open-weight model works well for this structured extraction task. The prompt's output schema is strict JSON, so enable structured output mode or JSON mode on your provider. Set a low temperature (0.0–0.1) for deterministic extraction. If the extraction fails schema validation, retry once with the validation error appended to the prompt as feedback. If the second attempt also fails, fall back to a keyword-only search without spatial filters and log the failure for review. For high-traffic systems, cache geocoding results by normalized place name to avoid redundant API calls. Never pass raw user queries directly to the geocoding service without extraction—users phrase locations in ways that geocoders misinterpret without normalization.