Geo-Point Datatype: Distance-Based Product Search in Virto Commerce
A geo-point is a single latitude and longitude pair pinned to a product, a branch, or any other indexed record. Once it is indexed as a spatial type rather than as text, the search engine can answer two questions that keyword search cannot: what is within this radius, and what is nearest.
Virto Commerce has carried GeoPoint as a first-class catalog property type since 2018. This article covers what it does, where it earns its place in B2B, how the query actually reaches Elasticsearch, and what it deliberately leaves to other tools.
The Short Version
- A geo-point stores one latitude and longitude pair, validated to ±90 and ±180.
- It powers three query primitives: filter by radius, sort by distance, and bucket results into distance bands.
- In B2B it answers the questions buyers actually ask: which branch has it, how far away, can I collect it today.
- It is a search primitive, not a store locator. You still build the map and the pickup flow on top.
- Distances are straight-line, not drive time. Coordinates have to be kept current, usually from the ERP.
What Is a Geo-Point Datatype?
A geo-point is the smallest possible unit of location data: one point on the surface of the Earth, expressed as a latitude and a longitude. Virto Commerce stores it as a value object that validates both halves on write: latitude between -90 and 90, longitude between -180 and 180. A malformed coordinate fails at the boundary instead of silently indexing as garbage.
The distinction that matters is typing. You can already put 52.3676, 4.9041 into a short-text property today, and the search engine will happily index it — as a string. Strings sort alphabetically and match exactly. They cannot tell you that Amsterdam is closer to Utrecht than to Milan. A geo-point field is indexed as a spatial type, so the engine understands the two numbers as a position and can do geometry with them.
GeoPoint sits in the catalog module’s list of property value types next to ShortText, LongText, Number, Integer, DateTime, Boolean, Html, Measure, and Color. It is configured the same way as any other property, which means merchandisers assign it from the admin UI without a developer in the loop.
Pic. Why the field type matters.
What the Geo-Point Datatype Enables
Indexing a coordinate is only useful if you can query it. The search service exposes three capabilities on top of a geo-point field, and they compose with everything else in the query — keywords, facets, price ranges, catalog scope.
|
Capability
|
What it does
|
What the buyer sees
|
|---|---|---|
|
Radius filter
|
Keeps only records whose coordinate falls within a given distance of an origin point
|
“In stock within 50 km”
|
|
Distance sorting
|
Orders the result set by how far each record is from the origin point
|
Nearest branch at the top of the list
|
|
Distance aggregation
|
Groups matching records into distance bands alongside the usual facets
|
“Under 10 km (4), 10–50 km (17)”
|
All three run inside the same request as the rest of the search. There is no second round trip to a mapping service and no post-filtering of results in application code, which is what keeps the latency budget intact on a catalog of any size.
Where Distance-Based Search Pays Off in B2B
Geolocation reads as a B2C feature — find the nearest coffee shop. In B2B it is usually about inventory and logistics, and the stakes are higher because the buyer is trying to keep a job site or a production line moving.
|
Scenario
|
The question being asked
|
Why distance decides it
|
|---|---|---|
|
Branch and depot networks
|
Which of our locations has this part?
|
The buyer wants the closest branch holding stock, not the first one alphabetically
|
|
Will-call and collection
|
Can I pick this up today?
|
A pickup point an hour away is a different offer from one across town
|
|
Field service and trades
|
What is available near the job site?
|
The origin point moves with the technician, not with the account address
|
|
Dealer and distributor locators
|
Who sells this in my area?
|
Territory coverage is geographic, so the ranking should be too
|
|
Multi-vendor marketplaces
|
Which seller can reach me fastest?
|
Proximity is a reasonable proxy for lead time when carriers are unknown
|
The common thread: in each case the buyer is not browsing. They know what they need and the only open question is where they can get it and how fast. Distance is the ranking signal that answers it. This is also why geo-point pairs naturally with click and collect, where the whole flow depends on surfacing the right pickup location first.
Distance is one signal. See what else the search service ranks on.
How It Works Under the Hood
The path from a coordinate in the admin UI to a sorted result set has four steps.
- A catalog property is defined with the
GeoPointvalue type and given a value inlatitude, longitudeform. - During indexing, the value is emitted as a field of type
GeoPointin the search document, which is a first-class member of the search module’s field-type enumeration rather than a special case. - The Elasticsearch provider maps that field to the native
geo_pointtype, so the coordinate is stored in a structure built for spatial lookups. - At query time, a
GeoDistanceFilterbecomes an Elasticsearchgeo_distancequery, and aGeoDistanceSortingFieldbecomes a_geo_distancesort. The provider currently expresses the radius in kilometres.
The abstraction is worth noting. Your application code talks to the search module’s filter and sorting model, not to Elasticsearch. Swapping the search provider does not rewrite your geo queries, which is the same separation the rest of the B2B ecommerce platform follows.
Pic. How a coordinate becomes a distance query.
What Geo-Point Does Not Do
Scoping this correctly saves an awkward conversation later. Geo-point search is a primitive, and there are four things it does not give you.
- Drive time and routing. Distance is measured as a straight line across the globe. For “within 50 km” that is the right model and it is fast. For “90 minutes by van in Tuesday traffic” you need a routing API, called after search has narrowed the candidates from thousands to a handful.
- A store locator UI. The engine returns ordered results. The map, the pins, the branch cards, and the browser location prompt are all frontend work.
- Provider independence. Radius filtering and distance sorting need a search engine with a spatial field type. On the Elasticsearch provider this works out of the box; a provider without spatial support will index the value but cannot answer distance queries against it.
- Fresh coordinates. A geo-point is only as good as the data behind it. Branch relocations and new depots have to flow through, which in practice means treating coordinates as part of the ERP integration rather than as a field someone remembers to update.
Designing search for a branch network?
The Architectural Guide sets out how catalog, search, and inventory fit together in a composable B2B build.
How to Add a Geo-Point Property
For a catalog that already runs on Virto Commerce, adding the capability is a configuration task rather than a development project.
- In the admin, open the catalog or category where the property should live and add a new property with the
GeoPointvalue type. - Populate it. For a handful of branches, type the coordinates in. For anything larger, map the field in your ERP or PIM sync so it arrives with the rest of the record.
- Reindex so the new field reaches the search engine with the correct mapping. A partial index over the affected catalog is enough.
- Add the geo filter and sort to the search request your storefront issues, passing the buyer’s location as the origin point.
- Handle the case where you have no origin. Browser geolocation gets declined, and a default such as the buyer’s account address or their assigned branch keeps the page useful instead of empty.
If you are running across several markets, read this alongside how multiregional commerce handles catalogs, pricing, and fulfilment per region. Distance-based search is one input into that model, not a substitute for it.
Conclusion
Geo-point is a small feature with a specific job. It turns a coordinate from a string that happens to contain numbers into something the search engine can reason about, and it does so behind an abstraction that keeps your code away from provider-specific query syntax.
For B2B sellers with branches, depots, dealers, or field stock, that is the difference between a catalog that tells the buyer a part exists and one that tells them where to pick it up this afternoon. The second answer is the one that closes the order.
FAQs
A geo-point is a single latitude and longitude pair that identifies one location on the Earth’s surface. Stored as a typed field rather than free text, it lets a search engine calculate distance from a point, test whether a location falls inside a bounding box, and group results into distance bands. In Virto Commerce, GeoPoint is one of the built-in catalog property value types, alongside ShortText, Number, DateTime, and Measure.
Three things. Filter to everything within a radius of a given point, sort results by distance from that point, and combine either with the ordinary facets and keyword terms already in the query. The search module exposes these as GeoDistanceFilter and GeoDistanceSortingField, which the Elasticsearch provider translates into a geo_distance query and a _geo_distance sort.
No. Distance is measured as a straight line across the surface of the globe, not along a road network. For “nearest branch” and “within 50 km” questions that is normally the right answer and it is fast. If you need drive time or turn-by-turn routing, call a mapping service after search has narrowed the candidate set.
Geo queries need a search engine that indexes coordinates as a spatial type. The Elasticsearch provider maps geo-point fields to the native geo_point type and supports both radius filtering and distance sorting. Providers without a spatial field type will index the value but cannot answer distance queries against it.
Usually from the system that already owns your branch, warehouse, or dealer master data, which is normally the ERP. Coordinates arrive through the same ERP integration that carries stock and pricing, and get written to the geo-point property during indexing. Manual entry works for a handful of locations; it stops being practical past a few dozen.
