Working with geo objects
Create geofences, POIs, and routes in different shapes using GeoJSON geometry.
Navixy Repository API is a work in progress. This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.
Geo objects in Navixy Repository API represent geographic features like geofences, points of interest, and routes. They store location data in GeoJSON format, making them useful for defining delivery zones, marking important locations, creating routes, and managing areas where your fleet operates.
This guide walks you through creating, updating, and managing geo objects with different geometry types.
Before you start
To work with geo objects, you need your organization's ID. Use the me query to find it through your membership:
query GetMyOrganization {
me {
... on User {
memberships {
nodes {
organization {
id
title
}
}
}
}
}
}The response returns your organization's details:
Use the id of the organization you want to work with for all subsequent geo object operations.
Check the available geo object types
Before creating a geo object, list the available types to see what options exist with this query:
The response returns predefined types and any custom types your organization has created:
If the response returns an empty array, doesn't contain the type you need, or you want a type with a different code or title, create one:
The response confirms the new type:
Save the type ID — you'll need it when creating geo objects.
Understanding GeoJSON geometry
Geo objects store their geographic shape in the geometry field, which uses GeoJSON format as defined in RFC 7946. This format represents geographic features with coordinate-based geometries.
The geometry field is a convenience alias for the geojson system custom field. You can also access the same data through the customFields field.
A complete GeoJSON is always a FeatureCollection wrapping one or more Feature objects, each of which holds a geometry and optional properties:
More examples of different geometry types wrapped in FeatureCollection can be found in the Common GeoJSON patterns section.
Supported geometry types
Point
A single coordinate marker. For GPS containment checks, use a Polygon centered on the point instead.
Warehouse pin on a map
Polygon
Area boundary. The only type that supports containsPoints checks.
Geofence
LineString
A straight or curved line passing through specific points. Useful for visual map overlays, but has no area and cannot be used for containment checks.
Road segment, boundary line
MultiPoint
Multiple separate coordinate markers
Distribution network
MultiLineString
Multiple line sequences
Multiple road segments
MultiPolygon
Multiple areas treated as a single geo object
Non-contiguous zones, city districts
Modeling routes for deviation detection: A GeoJSON LineString represents a line with no width. In fleet management, route monitoring works by detecting whether a vehicle leaves a defined corridor. This requires a zone with area — typically a Polygon shaped as a buffer around the intended path (sometimes called a "corridor" or "sausage" shape). Use LineString only for visual display purposes and Polygon for any containment or deviation logic.
Points and GPS presence detection: A Point geometry has no area, so containsPoints cannot be applied to it. If you need to detect whether a GPS device is near a specific location, create a Polygon centered on that location with an appropriate radius buffer instead of using a Point.
Coordinate format
GeoJSON uses [longitude, latitude] order, which is opposite to how coordinates are often written in text.
For example, Berlin's Brandenburg Gate is located at latitude 52.516275 and longitude 13.377704. In GeoJSON, this becomes [13.377704, 52.516275].
Always double-check coordinate order when converting from other formats. Swapped coordinates will place your location in the wrong part of the world.
For details on geometry structure, winding order for polygons, and coordinate reference systems, see RFC 7946 Section 3.1.
Custom fields
Geo objects support custom fields. You might want to add fields for:
Access restrictions (delivery time windows, vehicle type requirements)
Operational metadata (zone manager contact, capacity limits)
Business attributes (pricing tier, priority level)
See Implementing custom fields for details on defining and using custom fields.
Example scenario: Delivery service zones
A delivery company needs to define service areas and mark important locations. They start by creating an arrival zone around their main warehouse — a small polygon buffer that lets them detect when vehicles arrive or depart. Then they create a larger delivery zone, verify which addresses fall within it, and adjust boundaries as the business grows.
Create the arrival zone
Rather than a Point, model the warehouse as a small Polygon buffer centered on the building. This lets you use containsPoints later to detect vehicle arrivals and departures.
The polygon is a small rectangle roughly 30 × 45 meters centered on coordinates [13.404954, 52.520008] in Berlin's Mitte district. Adjust the offsets to match your actual site boundary.
The response confirms creation:
Save the id and version — you'll need them for updates.
Create a polygon-shaped delivery zone
Create a rectangular delivery zone covering central Berlin:
Note the coordinate structure:
The outer array contains one or more rings (here, just one exterior ring).
Each ring is an array of
[longitude, latitude]coordinate pairs.The first and last coordinates are identical, closing the ring.
The response returns:
Check test point containment
Check if specific delivery addresses fall within your zone using the containsPoints field:
The response shows which points are inside the zone:
The first two addresses fall within the zone, while the third is outside. This helps you validate which delivery requests you can accept.
The containsPoints method is only available for Polygon and MultiPolygon geometry types. It tests whether each point falls inside the polygon boundary.
Update the zone boundary
As your delivery business expands, you need to cover a larger area. Update the zone geometry to extend the boundaries:
The version parameter ensures you don't accidentally overwrite changes made by someone else. If the version doesn't match, you'll receive a conflict error.
The response shows the incremented version:
Common GeoJSON patterns
All geometry values in the API are wrapped in a FeatureCollection. The examples below show the complete structure you pass in mutations and receive in responses.
Single location marker (warehouse, customer address)
Rectangular area (simple geofence)
Polygon with exclusion zone (donut-shaped)
The first ring defines the exterior boundary. The second ring creates a hole — an area inside the outer boundary where the polygon doesn't apply. This is useful for delivery zones that exclude certain neighborhoods or restricted areas.
Route corridor (for deviation detection)
In fleet management, routes are modeled as Polygon corridors rather than LineString geometries. A corridor is a buffer zone around the intended path: if a vehicle leaves this zone, it has deviated from the route. The example below shows a narrow corridor along a Berlin street segment:
Use a wider corridor for highways where minor deviations are acceptable, and a narrower one for city routes requiring precise tracking.
Line overlay (visual display only)
Use LineString when you need to draw a line on a map for display purposes — for example, to show the planned path of a delivery or the boundary between two zones. A LineString has no area and cannot be used for containment checks.
Multiple warehouse locations
Listing geo objects
To retrieve all geo objects for an organization, use this query:
The response returns a paginated list:
You can filter by type or search by title:
The response returns only matching geo objects:
For more on filtering and pagination, see Filtering and sorting and Pagination.
Handling version conflicts
If someone else updates the geo object while you're working on it, your mutation will fail with a conflict error:
To resolve this:
Query the geo object to get the current version and geometry
Merge your changes with the current state
Retry the mutation with the correct version
For more details on version conflicts, see Optimistic locking.
See also
Geo objects reference: A complete list of all operations and types related to geo objects
Filtering and sorting: Full operator reference and value formats for custom field filters
Optimistic locking: How
versionworks in update and delete mutations
Last updated
Was this helpful?