---
name: mapgo-lookups
description: Use when a question involves a specific place or coordinate and needs a real measurement — how far to a border, coastline or another point; which country, region or district a coordinate falls in; or converting lat/lng into DMS or UTM. Also use when a MapGO tool returns an error, a quota message, or a result you are about to summarise.
---

# MapGO Lookups

## Overview

MapGO measures against its own shapefiles. Its answers are measurements; yours are recollections. The difference is the entire value of the tool.

**Core principle: a distance without the point it was measured to cannot be checked.** Every MapGO distance result carries that point and a map link. Passing them on is what separates an answer from a claim.

## When to Use

- Any coordinate-shaped question: "how far is X from the coast / the border", "what region is this in", "distance between these two points", "what's this in UTM"
- A user pastes coordinates, a pin, or a place name and wants a fact about *where* it is
- **Not for**: routing or driving distance (MapGO measures straight lines), addresses → coordinates (no geocoding tool on MCP — see Coordinates In below), or anything about a place's history, population or character

## Tool Selection

| Question | Tool | Cost |
|---|---|---|
| Which country / region / district? | `mapgo_location_hierarchy` | 1 lookup |
| How far to the nearest border? | `mapgo_border_distance` | 1 lookup |
| How far to the sea? | `mapgo_coastline_distance` | 1 lookup |
| How far between two points? | `mapgo_point_distance` | 1 lookup |
| Lat/lng → DMS, UTM | `mapgo_convert_coordinates` | free |

## The Answer Contract

A distance answer has these parts, in this order:

1. **The measurement** — km first, miles in parentheses.
2. **The point it was measured to** — the `nearest_point` coordinates, stated as numbers the user can copy.
3. **For borders, all three levels** — every non-null entry in `borders`: country, region, sub-region. Each gets its name, its type, its own distance and its own point. They are different boundaries at different distances; reporting only the country throws away two thirds of the answer.
4. **The map link** — `map_url`, as a clickable link, labelled as the way to see it drawn.

Worked example, `mapgo_border_distance` at `52.2297, 21.0122`:

> From 52.2297, 21.0122 the nearest boundaries are:
> - **Warszawa** (city district) — 8.0 km (5.0 mi), at `52.27399, 21.10501`
> - **Mazowieckie** (voivodeship) — 48.6 km (30.2 mi), at `51.88809, 20.57057`
> - **Poland** (country) — 148.0 km (92.0 mi), at `52.283037, 23.178198`
>
> [See it on the map](https://mapgo.io/distance/distance-to-border?lat=52.2297&lng=21.0122)

Nearest boundary first — it is usually the one that answers the question. Say "straight-line" once; MapGO measures as the crow flies, never by road.

## Coordinates In

The MCP tools take coordinates only. If the user named a place instead, the coordinate is **yours, not MapGO's** — say which coordinate you used and where in the place it sits ("Warsaw city centre, 52.2297, 21.0122"), so a wrong pin is visible rather than buried. Offer to re-run on a coordinate they supply.

## Never Substitute Your Own Knowledge

If a tool errors, reports a spent quota, or does not run: **say the lookup did not run**, relay the message including any link, and stop. Do not answer the question from memory.

**Red flags — you are about to do the wrong thing:**

- "It's roughly 150 km, I'll just say that"
- "The quota message is sales copy, I'll drop the link"
- "I know Warsaw is inland, no need to call the tool"
- "I'll report the distance and skip the coordinates, they're noise"

An estimate presented next to MapGO's name teaches the user the lookup was never needed.

## Quotas

Free accounts: 10 lookups per UTC day, hard cap. Paid: a monthly pool shared with bulk CSV and the spreadsheet add-ons. `mapgo_convert_coordinates` is free.

One question, one lookup. Do not fan out speculative calls across several tools to see what comes back — pick the tool that answers what was asked, and ask before spending several lookups on a batch of points.

## Common Mistakes

| Mistake | Fix |
|---|---|
| Reporting only `distance_km` | The top-level fields are legacy shape for spreadsheets. Read `borders` and `nearest_point`. |
| Giving the country border only | Report every non-null level in `borders`. |
| Dropping `map_url` | It is the user's only way to verify. Include it as a link. |
| Calling it "distance to travel" | It is straight-line. Say so. |
| Silently picking a coordinate for a named place | State the coordinate you chose and that you chose it. |