Sheets and layers
A country is one address sheet. Everything else comes as a separate file you put beside it: the named places of the country, your own places, the towns of the world. Each file is optional, and without it the engine answers exactly as before.
The four files
| File | What it holds | How you add it | When the engine asks it | Flag on its answers |
|---|---|---|---|---|
the address sheet (france.bin) | the country's addresses: houses, streets, towns, postcodes | the first argument | always | — |
your own places (depots.bin) | names you give: sites, buildings, depots | --also | first, before the address sheet | own_sheet |
the place layer of the country (fr_poi.bin) | named places: stations, museums, shops, hospitals | --poi | only when the address answer is empty or weak | poi_layer |
the world sheet of towns (world_places.bin) | towns and cities of every country | --also-after | when the query names another country, or the address sheet found no house or street | world_place |
Only the address sheet is needed to geocode addresses. The others are smaller or larger downloads of their own: the file table is under Getting the files.
The order the engine asks them in
- 1. Your own places (
--also). A name your sheet knows is answered from it, and nothing else is asked. - 2. Another country. A query that ends with the name of another country (“Berlin, Germany” on the French sheet), when a world sheet is passed, goes to it only: the address sheet cannot hold a town of another country.
- 3. The address sheet. Every other query is asked here, the same way as with no extra file.
- 4. The place layer (
--poi), only when the address answer is empty or weak, and only if its own answer is surer. A confident address is never replaced. - 5. The world sheet (
--also-after), when there is still no house or street: the query is read as the name of a town.
Each answer says which file gave it: the flag in the table above, and with --with provenance the card of that file, its licence included (extra fields).
Addresses only
With the address sheet alone, an address is a house, and the name of a place is at best a street with a similar name, marked weak:
$ gridpin query france.bin "8 Boulevard du Port, Amiens" -k 1 $ gridpin query france.bin "Gare de Lyon, Paris" -k 1
| Query | Answer | Precision | Answered by | Weak |
|---|---|---|---|---|
| 8 Boulevard du Port, Amiens | Boulevard du Port 8, Amiens | house | address sheet | no |
| Gare de Lyon, Paris | Rue de Lyon, Paris 12e Arrondissement | street | address sheet | yes |
Add the places of the country
Pass the place layer with --poi. The station is now found by its name, and the answer carries poi_layer. The address of the first example is answered by the address sheet as before:
$ gridpin query france.bin "Gare de Lyon, Paris" -k 1 --poi fr_poi.bin $ gridpin query france.bin "8 Boulevard du Port, Amiens" -k 1 --poi fr_poi.bin
| Query | Answer | Precision | Answered by | Weak |
|---|---|---|---|---|
| Gare de Lyon, Paris | Gare de Lyon, Paris | street | place layer (poi_layer) | no |
| 8 Boulevard du Port, Amiens | Boulevard du Port 8, Amiens | house | address sheet | no |
The cascade and its other forms (Python, DuckDB): POI layer.
Put your own places first
Build a sheet from a table of your places (name, point, optional group, code and other names) and pass it with --also. It is asked before the address sheet, so a name you defined always wins:
name,lat,lon,group,code,aliases Depot Nord,48.8975,2.3600,Logistique,D1,Entrepôt Nord Depot Sud,48.8150,2.3640,Logistique,D2,
$ gridpin build --places depots.csv depots.bin … 2 places -> depots.bin
$ gridpin query france.bin "Depot Nord" -k 1 --also depots.bin
| Query | Answer | Precision | Answered by | Weak |
|---|---|---|---|---|
| Depot Nord | Depot Nord, Logistique | street | your own places (own_sheet) | no |
Every field of the table and its limits: a sheet of your own places.
Towns of other countries
The address sheet of France holds no town of Germany. With the world sheet after it (--also-after) a town of another country is answered as a town, marked weak:
$ gridpin query france.bin "Berlin, Germany" -k 1 --also-after world_places.bin
| Query | Answer | Precision | Answered by | Weak |
|---|---|---|---|---|
| Berlin, Germany | Berlin, DE-BE | city | world sheet (world_place) | yes |
How to get the world sheet and what it covers: towns of any country.
All of them at once
The files combine. Each query below is answered by the file the order above gives it: your depot, the station, the town in Germany, the house:
$ gridpin query france.bin "Depot Nord" -k 1 --also depots.bin --poi fr_poi.bin --also-after world_places.bin $ gridpin query france.bin "Gare de Lyon, Paris" -k 1 --also depots.bin --poi fr_poi.bin --also-after world_places.bin $ gridpin query france.bin "Berlin, Germany" -k 1 --also depots.bin --poi fr_poi.bin --also-after world_places.bin $ gridpin query france.bin "8 Boulevard du Port, Amiens" -k 1 --also depots.bin --poi fr_poi.bin --also-after world_places.bin
| Query | Answer | Precision | Answered by | Weak |
|---|---|---|---|---|
| Depot Nord | Depot Nord, Logistique | street | your own places (own_sheet) | no |
| Gare de Lyon, Paris | Gare de Lyon, Paris | street | place layer (poi_layer) | no |
| Berlin, Germany | Berlin, DE-BE | city | world sheet (world_place) | yes |
| 8 Boulevard du Port, Amiens | Boulevard du Port 8, Amiens | house | address sheet | no |
Turn a layer on and off
- A layer is on when you pass its file, and off when you do not: no setting is stored anywhere.
- The files do not change each other. Adding a layer adds answers where the address sheet had none or a weak one; it does not move a confident address.
- Swap a layer by passing another file: a newer place layer, or your own places of another site.
- In a batch, the answers of each layer stay marked, so you can keep or drop them by their flag.
| Where | Address sheet | Your own places | Place layer | World sheet |
|---|---|---|---|---|
gridpin query, batch, serve | first argument | --also | --poi | --also-after |
| Python | Geocoder(sheet) | also= | poi= | — |
| DuckDB | gridpin_load(path) | — | gridpin_load_poi(path) | — |
| MCP server | the sheet setting | GRIDPIN_OWN_SHEET | — | — |
Limits
- A place layer answers with the point of the place, not of its entrance or its address.
- An answer of the place layer or of the world sheet can be weak: check the
weakfield before you use it as a confirmed location. - The world sheet answers towns, not addresses in them.
- Each file keeps its own licence; the answer's provenance names it.
All the keys of each command: command reference. Recipes that use the files together: your own places, nearest and zones.