An empty result is not an error. Tools that can legitimately find nothing — no address match, no
territory covering a point — return an empty result with
isError: false. An agent that treats
those as failures will retry in a loop and consume transactions for nothing.placematic_assign_territory
Determines which of your delivery territories or sales grids cover a point, which of your locations
serve it, and on what delivery terms. Answers from your own configuration held in Placematic — not
from postal or administrative geography.
number
required
Longitude in decimal degrees, WGS84. Note the axis order:
x is longitude. In the United
States this value is negative.number
required
Latitude in decimal degrees, WGS84.
latitude and
longitude. This is the most common source of transposed coordinates when writing against the API
directly.
Response
deliveryPrice and orderValue are integers in cents. 3000 is $30.00. There is no currency field
in the response today; amounts are assumed to be in the currency of your Placematic contract.
distance is in metres, straight-line from the queried point to the serving location. It is not a
driving distance. Use placematic_route if driving distance matters.
evaluated_at is the time the query ran. Territory data is live — if the configuration is edited,
the answer changes. There is no versioned snapshot.
Empty result: a point outside every territory returns an empty territories array. This is a
valid business answer.
placematic_route
Road distance, driving time and toll cost between two points, with a truck profile that respects
vehicle restrictions in the HERE road network.
number
required
number
required
number
required
number
required
string
default:"car"
car or truck. Use truck for any commercial goods vehicle.integer
Vehicle height in centimetres. A standard US semi at 13 ft 6 in is
411.integer
Gross vehicle weight in kilograms. 80,000 lb is
36287.integer
Vehicle length in centimetres. A 53 ft trailer combination is about
1615.integer
Number of axles. A standard US 5-axle semi is
5. Toll rates are charged by axle — omitting this
materially changes the cost estimate.tolls.total is the sum of all fares on the route, in tolls.currency. tolls.points counts
individual fares, not distinct toll systems — one tollway can charge at several gantries, which is
why four points map to two systems above. A route with no tolls returns total: 0 and points: 0.
Results are not deterministic and are not intended to be. Travel time depends on conditions at the
time of the call. computed_for states what the number was computed under, so the result can be
reproduced and audited.
Empty result: no route returns an empty result rather than an error. For a truck this usually
means the dimensions make every path illegal, not that no road exists.
Not available: departure time scheduling, waypoints, route geometry (polyline), and traffic
analytics. Asset-based pricing, US Traffic Analytics and the Safety Cameras Feed require an
enterprise HERE entitlement and are not exposed.
placematic_geocode
Turns a complete postal address into coordinates.
string
required
The full postal address or place name. Minimum 3 characters, maximum 300.
integer
default:"1"
Number of candidate matches to return, ordered by match quality. 1–10.
estimatedPointAddress return an access point that is a projection onto the road centreline and
carries no additional information — both such addresses in the sample had the smallest offsets in
the set.
Whether that offset changes a route depends on whether the two points snap to the same road segment.
On three addresses tested, one produced truck routes 2.6 km apart approaching from different sides
of the site; the other two produced routes within 60 m of each other. Use the access point where one
is present — it is never worse, and occasionally it is the difference between a dock and a fence.
Empty result: no match returns an empty matches array with guidance to add a city or postal
code.
placematic_reverse_geocode
Turns coordinates into the nearest postal address.
number
required
Decimal degrees, WGS84. Positive north of the equator.
number
required
Decimal degrees, WGS84. Positive east of Greenwich — negative in the United States.
integer
default:"1"
Number of nearby addresses to return, nearest first. 1–10.
placematic_geocode.
Empty result: offshore or unmapped coordinates return an empty matches array.
Errors
Tool-level failures returnisError: true with a plain-language message the agent can act on.
Argument validation happens in the MCP layer. A malformed call costs no transaction.
Not yet available
Documented here so you do not design around them.placematic_search_nearby — your locations within a radius of a point. Planned.
placematic_search_address — ranked candidates for a partial or ambiguous string. Planned, and the
correct tool for the “downtown Chicago” case above.
Dataset version in responses — planned in the REST layer.