@zukall/zap 0.2.1 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/PROTOCOL.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# ZAP — Zukall Addressing Protocol, version 2
|
|
2
2
|
|
|
3
3
|
Protocol 2 uses **100-meter grid blocks** and **1-meter detail**, computed from
|
|
4
|
-
unrounded projected GPS coordinates. The npm package version (`0.2.
|
|
4
|
+
unrounded projected GPS coordinates. The npm package version (`0.2.3`) and
|
|
5
5
|
protocol version (`2`) are separate. Previously issued protocol-1 addresses retain
|
|
6
6
|
their original text and identity; see [PROTOCOL-V1.md](PROTOCOL-V1.md).
|
|
7
7
|
|
package/README.md
CHANGED
|
@@ -1,9 +1,130 @@
|
|
|
1
1
|
# ZAP — Zukall Addressing Protocol
|
|
2
2
|
|
|
3
3
|
**`@zukall/zap`** generates addresses directly from latitude and longitude using
|
|
4
|
-
fixed country/province grids.
|
|
5
|
-
|
|
6
|
-
|
|
4
|
+
fixed country/province grids.
|
|
5
|
+
|
|
6
|
+
**Give real places a recognizable address, without waiting for street names or
|
|
7
|
+
house numbers.**
|
|
8
|
+
|
|
9
|
+
Imagine building a courier application that serves Uganda, Haiti, Florida in
|
|
10
|
+
the United States, and Germany. Your couriers and remote dispatchers need to
|
|
11
|
+
recognize addresses quickly, even when those places use different languages,
|
|
12
|
+
street names, and numbering systems.
|
|
13
|
+
|
|
14
|
+
With ZAP, they learn one address format and use it across the configured
|
|
15
|
+
countries and states. A home, business, rural entrance, or pickup point can have
|
|
16
|
+
an address based on its GPS location. A dispatcher can read the same address
|
|
17
|
+
structure in each market. Your application can show a courier where a
|
|
18
|
+
destination lies relative to their current location in the same grid, then open
|
|
19
|
+
map directions using the destination’s saved GPS point.
|
|
20
|
+
|
|
21
|
+
Once you have the GPS coordinates, you can generate the address offline,
|
|
22
|
+
without a geocoding service, API key, or per-address fee. ZAP works alongside
|
|
23
|
+
existing street addresses and also gives you a location address where street
|
|
24
|
+
names or house numbers are missing.
|
|
25
|
+
|
|
26
|
+
## See how ZAP works: Haiti’s grid
|
|
27
|
+
|
|
28
|
+
ZAP starts with a configured rectangle around a country. Where a country uses
|
|
29
|
+
province or state grids, it uses the selected province’s rectangle instead—for
|
|
30
|
+
example, Florida’s grid within the United States.
|
|
31
|
+
|
|
32
|
+
Each rectangle has a fixed center and two axes: north/south and east/west.
|
|
33
|
+
Think of laying a grid of **100 × 100-meter square blocks** across the area.
|
|
34
|
+
The main address numbers count complete blocks from the center, and the
|
|
35
|
+
direction letters tell you which side of the center the location is on.
|
|
36
|
+
|
|
37
|
+
A suffix such as **`#23-43`** adds the position within that block: 23 whole meters
|
|
38
|
+
along the address’s north/south direction and 43 along its east/west direction.
|
|
39
|
+
That gives a home, entrance, or pickup point a location code with whole-meter
|
|
40
|
+
detail. Keep apartment and unit numbers alongside the code as separate details.
|
|
41
|
+
|
|
42
|
+
The Haiti illustrations below show the same fixed grid in use. Each address
|
|
43
|
+
comes from its own GPS point. Roads can run straight, diagonally, or curve;
|
|
44
|
+
the grid’s center and axes stay fixed.
|
|
45
|
+
|
|
46
|
+
### Whole-country grid and fixed center
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
The Haiti grid has one fixed center: **19.0578675° N, 73.0641385° W**.
|
|
51
|
+
It is the center of the configured rectangle, in the Gulf of Gonâve, rather than
|
|
52
|
+
the capital or a street junction. Every Haiti address uses that same origin.
|
|
53
|
+
North/south and east/west offsets start there and increase away from it.
|
|
54
|
+
|
|
55
|
+
| Configured rectangle edge | GPS limit |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| North | 20.089789° N |
|
|
58
|
+
| South | 18.025946° N |
|
|
59
|
+
| West | 74.489167° W |
|
|
60
|
+
| East | 71.639110° W |
|
|
61
|
+
|
|
62
|
+
The whole-country overview is **schematic and not to scale**. Its grid lines
|
|
63
|
+
make the fixed axes visible; the calculation panel explains **100-meter blocks**
|
|
64
|
+
and the two whole-meter remainders. The coastline is illustrative. The configured
|
|
65
|
+
rectangle includes sea and is not an administrative boundary.
|
|
66
|
+
|
|
67
|
+
For the Marriott example, GPS **(18.532731, -72.324187)** projects to
|
|
68
|
+
−58,229.5607 meters northing and +78,013.0303 meters easting. Flooring their
|
|
69
|
+
absolute values gives 58,229 whole meters south and 78,013 east: **582 S 780 E
|
|
70
|
+
#29-13, Port-au-Prince, HT ZAP**. The suffix records another 29 whole meters
|
|
71
|
+
south and 13 east after the complete blocks. Use the saved GPS point for navigation.
|
|
72
|
+
|
|
73
|
+
**Current suffix notation is `#42-68`.** The north–south and east–west images use
|
|
74
|
+
the compact notation `#4268` for the same two remainders: 42 south and 68 east.
|
|
75
|
+
The examples and captions below use the current dashed format.
|
|
76
|
+
|
|
77
|
+
### North–south: easting stays fixed
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
```text
|
|
82
|
+
Point A: 580 S 772 E #42-68, HT ZAP
|
|
83
|
+
Point B: 581 S 772 E #42-68, HT ZAP
|
|
84
|
+
Point C: 582 S 772 E #42-68, HT ZAP
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
From A to B, the location moves 100 projected meters south: the south block
|
|
88
|
+
increases from 580 to 581, while the east block and both remainders stay fixed.
|
|
89
|
+
Moving north on this side of the origin decreases the south block.
|
|
90
|
+
|
|
91
|
+
### East–west: northing stays fixed
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
```text
|
|
96
|
+
Point A: 582 S 770 E #42-68, HT ZAP
|
|
97
|
+
Point B: 582 S 771 E #42-68, HT ZAP
|
|
98
|
+
Point C: 582 S 772 E #42-68, HT ZAP
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
From A to B, the location moves 100 projected meters east: the east block
|
|
102
|
+
increases from 770 to 771, while the south block and both remainders stay fixed.
|
|
103
|
+
Moving west on this side of the origin decreases the east block.
|
|
104
|
+
|
|
105
|
+
### Diagonal streets: both axes can change
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
Point A: 580 S 770 E #43-46, HT ZAP
|
|
111
|
+
Point B: 581 S 771 E #12-36, HT ZAP
|
|
112
|
+
Point C: 582 S 772 E #08-41, HT ZAP
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Both axes and their remainders can change along a diagonal or curved street.
|
|
116
|
+
For point C, the whole-meter magnitudes are `582 × 100 + 08 = 58,208` south
|
|
117
|
+
and `772 × 100 + 41 = 77,241` east. The `#08-41` suffix keeps its leading zero.
|
|
118
|
+
|
|
119
|
+
The images are illustrative grid examples. To reach a real place, use its saved
|
|
120
|
+
GPS entrance point for road directions; the grid comparison describes relative
|
|
121
|
+
position rather than a route through buildings or other obstacles. The same
|
|
122
|
+
encoding applies to the other configured countries and provinces.
|
|
123
|
+
|
|
124
|
+
The README uses four compressed WebP illustrations, each below 100 KB.
|
|
125
|
+
Original PNGs remain in the source project; only the smaller WebP versions are
|
|
126
|
+
included in the npm package. The compressed package stays below 400 KB,
|
|
127
|
+
including all four illustrations.
|
|
7
128
|
|
|
8
129
|
```text
|
|
9
130
|
1194 S 382 E #16-20, Kampala, UG ZAP
|
|
@@ -37,7 +158,7 @@ grids or explicitly selected province/state grids. Coverage follows those
|
|
|
37
158
|
configurations; adding an unconfigured country requires a versioned grid
|
|
38
159
|
definition. The address structure stays consistent across them.
|
|
39
160
|
|
|
40
|
-
**Haiti is the illustrated example
|
|
161
|
+
**Haiti is the illustrated example above.** Its `HT` configuration provides one
|
|
41
162
|
fixed country grid, so a place can be addressed even when its street name,
|
|
42
163
|
building number, or formal address record is unavailable. This shows independence
|
|
43
164
|
from official address assignment; the method also works alongside existing
|
|
@@ -52,13 +173,15 @@ position. Saved GPS coordinates connect that destination to road directions.
|
|
|
52
173
|
|
|
53
174
|
| Location | Conventional address | ZAP address |
|
|
54
175
|
| --- | --- | --- |
|
|
55
|
-
| **Miami, USA — City Hall** | 3500 Pan American Drive, Miami, FL 33133, USA. | `2220 S 3602 E #92-35, Miami, FL US ZAP` |
|
|
56
|
-
| **Beijing, China — Sofitel Beijing Central** | No. 2 Jianguomen South Avenue, Chaoyang District, Beijing 100022, China. | `375 S 15 W #62-74, Beijing, BJ CN ZAP` |
|
|
57
|
-
| **Abidjan, Côte d’Ivoire — Sofitel Hotel Ivoire** | Boulevard Hassan II, Cocody, 08 BP 01 Abidjan, Côte d’Ivoire. | `2452 S 1724 E #88-29, Abidjan, CI ZAP` |
|
|
58
|
-
| **Port-au-Prince, Haiti — Marriott Hotel** | 147 Avenue Jean Paul II, Turgeau, Port-au-Prince, HT 6113, Haiti. | `582 S 780 E #29-13, Port-au-Prince, HT ZAP` |
|
|
59
|
-
| **Berlin, Germany — Brandenburg Gate** | Pariser Platz 5, 10117 Berlin, Germany. | `1538 N 1989 E #91-52, Berlin, DE ZAP` |
|
|
176
|
+
| **Miami, USA — City Hall** | 3500 Pan American Drive, Miami, FL 33133, USA. (25.7276845, -80.2337652) | `2220 S 3602 E #92-35, Miami, FL US ZAP` |
|
|
177
|
+
| **Beijing, China — Sofitel Beijing Central** | No. 2 Jianguomen South Avenue, Chaoyang District, Beijing 100022, China. (39.906274, 116.436733) | `375 S 15 W #62-74, Beijing, BJ CN ZAP` |
|
|
178
|
+
| **Abidjan, Côte d’Ivoire — Sofitel Hotel Ivoire** | Boulevard Hassan II, Cocody, 08 BP 01 Abidjan, Côte d’Ivoire. (5.326842, -4.005485) | `2452 S 1724 E #88-29, Abidjan, CI ZAP` |
|
|
179
|
+
| **Port-au-Prince, Haiti — Marriott Hotel** | 147 Avenue Jean Paul II, Turgeau, Port-au-Prince, HT 6113, Haiti. (18.532731, -72.324187) | `582 S 780 E #29-13, Port-au-Prince, HT ZAP` |
|
|
180
|
+
| **Berlin, Germany — Brandenburg Gate** | Pariser Platz 5, 10117 Berlin, Germany. (52.5162, 13.3780) | `1538 N 1989 E #91-52, Berlin, DE ZAP` |
|
|
181
|
+
|
|
182
|
+
*Coordinates are (latitude, longitude), in decimal degrees. Each displayed GPS point reproduces the adjacent ZAP address using package version 0.2.0. They demonstrate the format; the points are not independently verified entrances.*
|
|
60
183
|
|
|
61
|
-
|
|
184
|
+
Map/GPS references: [Miami City Hall](https://www.miami.gov/Notices/Events-Activities/City-of-Miami-Holiday-Festival), [Sofitel Beijing Central](https://all.accor.com/hotel/B628/index.en.shtml), [Sofitel Hotel Ivoire](https://all.accor.com/hotel/8844/index.en.shtml), [Marriott Port-au-Prince](https://www.marriott.com/en-us/hotels/papmc-marriott-port-au-prince-hotel/overview/), and [Brandenburg Gate visitor information](https://www.visitberlin.de/en/brandenburg-gate).
|
|
62
185
|
|
|
63
186
|
Street names, languages, address order, and postal components vary. ZAP uses the same generation function and encoding structure across its configured grids.
|
|
64
187
|
|
|
@@ -89,68 +212,6 @@ For navigation, use the original saved GPS coordinates—preferably the entrance
|
|
|
89
212
|
|
|
90
213
|
ZAP complements existing addresses. Whole-meter encoding does not guarantee one-meter GPS accuracy, and a location code does not automatically identify a unique household or apartment.
|
|
91
214
|
|
|
92
|
-
## See the address grid: Haiti illustrations
|
|
93
|
-
|
|
94
|
-
These illustrations show locations in the same fixed Haiti grid. Each address
|
|
95
|
-
is derived independently from its coordinates. The road can run north–south,
|
|
96
|
-
east–west, diagonally, or curve; the grid origin and axes stay fixed.
|
|
97
|
-
|
|
98
|
-
**Current suffix notation is `#42-68`.** The north–south and east–west images use
|
|
99
|
-
the compact notation `#4268` for the same two remainders: 42 south and 68 east.
|
|
100
|
-
The examples and captions below use the current dashed format.
|
|
101
|
-
|
|
102
|
-
### North–south: easting stays fixed
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
```text
|
|
107
|
-
Point A: 580 S 772 E #42-68, HT ZAP
|
|
108
|
-
Point B: 581 S 772 E #42-68, HT ZAP
|
|
109
|
-
Point C: 582 S 772 E #42-68, HT ZAP
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
From A to B, the location moves 100 projected meters south: the south block
|
|
113
|
-
increases from 580 to 581, while the east block and both remainders stay fixed.
|
|
114
|
-
Moving north on this side of the origin decreases the south block.
|
|
115
|
-
|
|
116
|
-
### East–west: northing stays fixed
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
```text
|
|
121
|
-
Point A: 582 S 770 E #42-68, HT ZAP
|
|
122
|
-
Point B: 582 S 771 E #42-68, HT ZAP
|
|
123
|
-
Point C: 582 S 772 E #42-68, HT ZAP
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
From A to B, the location moves 100 projected meters east: the east block
|
|
127
|
-
increases from 770 to 771, while the south block and both remainders stay fixed.
|
|
128
|
-
Moving west on this side of the origin decreases the east block.
|
|
129
|
-
|
|
130
|
-
### Diagonal streets: both axes can change
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
```text
|
|
135
|
-
Point A: 580 S 770 E #43-46, HT ZAP
|
|
136
|
-
Point B: 581 S 771 E #12-36, HT ZAP
|
|
137
|
-
Point C: 582 S 772 E #08-41, HT ZAP
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
Both axes and their remainders can change along a diagonal or curved street.
|
|
141
|
-
For point C, the whole-meter magnitudes are `582 × 100 + 08 = 58,208` south
|
|
142
|
-
and `772 × 100 + 41 = 77,241` east. The `#08-41` suffix keeps its leading zero.
|
|
143
|
-
|
|
144
|
-
The images are illustrative grid examples. To reach a real place, use its saved
|
|
145
|
-
GPS entrance point for road directions; the grid comparison describes relative
|
|
146
|
-
position rather than a route through buildings or other obstacles. The same
|
|
147
|
-
encoding applies to the other configured countries and provinces.
|
|
148
|
-
|
|
149
|
-
The README uses three compressed WebP illustrations, each 95–98 KB and 1280
|
|
150
|
-
pixels wide. Original PNGs remain in the source project; only the smaller WebP
|
|
151
|
-
versions are included in the npm package. The compressed package stays below
|
|
152
|
-
400 KB, including all three illustrations.
|
|
153
|
-
|
|
154
215
|
## Installation and local verification
|
|
155
216
|
|
|
156
217
|
After publication:
|
|
@@ -162,7 +223,7 @@ npm install @zukall/zap
|
|
|
162
223
|
Before publication, install the verified local package:
|
|
163
224
|
|
|
164
225
|
```sh
|
|
165
|
-
npm install /absolute/path/to/zukall-address-protocol/.artifacts/zukall-zap-0.2.
|
|
226
|
+
npm install /absolute/path/to/zukall-address-protocol/.artifacts/zukall-zap-0.2.3.tgz
|
|
166
227
|
```
|
|
167
228
|
|
|
168
229
|
Build and verify the source:
|
|
@@ -542,11 +603,11 @@ removed-option error.
|
|
|
542
603
|
```sh
|
|
543
604
|
npm login
|
|
544
605
|
npm run pack:check
|
|
545
|
-
npm publish ./.artifacts/zukall-zap-0.2.
|
|
606
|
+
npm publish ./.artifacts/zukall-zap-0.2.3.tgz --access public
|
|
546
607
|
```
|
|
547
608
|
|
|
548
609
|
An npm account with permission to publish `@zukall/zap` is required. Building and
|
|
549
|
-
packing do not publish the package. Package version is `0.2.
|
|
610
|
+
packing do not publish the package. Package version is `0.2.3`; current protocol
|
|
550
611
|
version is `2`, while preserved legacy results remain version `1`.
|
|
551
612
|
|
|
552
613
|
## License
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED