@zukall/zap 0.2.1 → 0.2.2
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.2`) 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
|
@@ -5,6 +5,95 @@ fixed country/province grids. Protocol **2** encodes **100-meter blocks** and
|
|
|
5
5
|
separate **whole-meter remainders**. It needs no Google Places API, geocoding
|
|
6
6
|
service, network request, or runtime dependency. Generation works offline.
|
|
7
7
|
|
|
8
|
+
## See how ZAP works: Haiti’s grid
|
|
9
|
+
|
|
10
|
+
These illustrations show locations in the same fixed Haiti grid. Each address
|
|
11
|
+
is derived independently from its coordinates. The road can run north–south,
|
|
12
|
+
east–west, diagonally, or curve; the grid origin and axes stay fixed.
|
|
13
|
+
|
|
14
|
+
### Whole-country grid and fixed center
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
The Haiti grid has one fixed center: **19.0578675° N, 73.0641385° W**.
|
|
19
|
+
It is the center of the configured rectangle, in the Gulf of Gonâve, rather than
|
|
20
|
+
the capital or a street junction. Every Haiti address uses that same origin.
|
|
21
|
+
North/south and east/west offsets start there and increase away from it.
|
|
22
|
+
|
|
23
|
+
| Configured rectangle edge | GPS limit |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| North | 20.089789° N |
|
|
26
|
+
| South | 18.025946° N |
|
|
27
|
+
| West | 74.489167° W |
|
|
28
|
+
| East | 71.639110° W |
|
|
29
|
+
|
|
30
|
+
The whole-country overview is **schematic and not to scale**. Its grid lines
|
|
31
|
+
make the fixed axes visible; the calculation panel explains **100-meter blocks**
|
|
32
|
+
and the two whole-meter remainders. The coastline is illustrative. The configured
|
|
33
|
+
rectangle includes sea and is not an administrative boundary.
|
|
34
|
+
|
|
35
|
+
For the Marriott example, GPS **(18.532731, -72.324187)** projects to
|
|
36
|
+
−58,229.5607 meters northing and +78,013.0303 meters easting. Flooring their
|
|
37
|
+
absolute values gives 58,229 whole meters south and 78,013 east: **582 S 780 E
|
|
38
|
+
#29-13, Port-au-Prince, HT ZAP**. The suffix records another 29 whole meters
|
|
39
|
+
south and 13 east after the complete blocks. Use the saved GPS point for navigation.
|
|
40
|
+
|
|
41
|
+
**Current suffix notation is `#42-68`.** The north–south and east–west images use
|
|
42
|
+
the compact notation `#4268` for the same two remainders: 42 south and 68 east.
|
|
43
|
+
The examples and captions below use the current dashed format.
|
|
44
|
+
|
|
45
|
+
### North–south: easting stays fixed
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
Point A: 580 S 772 E #42-68, HT ZAP
|
|
51
|
+
Point B: 581 S 772 E #42-68, HT ZAP
|
|
52
|
+
Point C: 582 S 772 E #42-68, HT ZAP
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
From A to B, the location moves 100 projected meters south: the south block
|
|
56
|
+
increases from 580 to 581, while the east block and both remainders stay fixed.
|
|
57
|
+
Moving north on this side of the origin decreases the south block.
|
|
58
|
+
|
|
59
|
+
### East–west: northing stays fixed
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
Point A: 582 S 770 E #42-68, HT ZAP
|
|
65
|
+
Point B: 582 S 771 E #42-68, HT ZAP
|
|
66
|
+
Point C: 582 S 772 E #42-68, HT ZAP
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
From A to B, the location moves 100 projected meters east: the east block
|
|
70
|
+
increases from 770 to 771, while the south block and both remainders stay fixed.
|
|
71
|
+
Moving west on this side of the origin decreases the east block.
|
|
72
|
+
|
|
73
|
+
### Diagonal streets: both axes can change
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
```text
|
|
78
|
+
Point A: 580 S 770 E #43-46, HT ZAP
|
|
79
|
+
Point B: 581 S 771 E #12-36, HT ZAP
|
|
80
|
+
Point C: 582 S 772 E #08-41, HT ZAP
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Both axes and their remainders can change along a diagonal or curved street.
|
|
84
|
+
For point C, the whole-meter magnitudes are `582 × 100 + 08 = 58,208` south
|
|
85
|
+
and `772 × 100 + 41 = 77,241` east. The `#08-41` suffix keeps its leading zero.
|
|
86
|
+
|
|
87
|
+
The images are illustrative grid examples. To reach a real place, use its saved
|
|
88
|
+
GPS entrance point for road directions; the grid comparison describes relative
|
|
89
|
+
position rather than a route through buildings or other obstacles. The same
|
|
90
|
+
encoding applies to the other configured countries and provinces.
|
|
91
|
+
|
|
92
|
+
The README uses four compressed WebP illustrations, each below 100 KB.
|
|
93
|
+
Original PNGs remain in the source project; only the smaller WebP versions are
|
|
94
|
+
included in the npm package. The compressed package stays below 400 KB,
|
|
95
|
+
including all four illustrations.
|
|
96
|
+
|
|
8
97
|
```text
|
|
9
98
|
1194 S 382 E #16-20, Kampala, UG ZAP
|
|
10
99
|
2106 S 3614 E #22-64, Miami, FL US ZAP
|
|
@@ -37,7 +126,7 @@ grids or explicitly selected province/state grids. Coverage follows those
|
|
|
37
126
|
configurations; adding an unconfigured country requires a versioned grid
|
|
38
127
|
definition. The address structure stays consistent across them.
|
|
39
128
|
|
|
40
|
-
**Haiti is the illustrated example
|
|
129
|
+
**Haiti is the illustrated example above.** Its `HT` configuration provides one
|
|
41
130
|
fixed country grid, so a place can be addressed even when its street name,
|
|
42
131
|
building number, or formal address record is unavailable. This shows independence
|
|
43
132
|
from official address assignment; the method also works alongside existing
|
|
@@ -52,13 +141,15 @@ position. Saved GPS coordinates connect that destination to road directions.
|
|
|
52
141
|
|
|
53
142
|
| Location | Conventional address | ZAP address |
|
|
54
143
|
| --- | --- | --- |
|
|
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` |
|
|
144
|
+
| **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` |
|
|
145
|
+
| **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` |
|
|
146
|
+
| **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` |
|
|
147
|
+
| **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` |
|
|
148
|
+
| **Berlin, Germany — Brandenburg Gate** | Pariser Platz 5, 10117 Berlin, Germany. (52.5162, 13.3780) | `1538 N 1989 E #91-52, Berlin, DE ZAP` |
|
|
60
149
|
|
|
61
|
-
*
|
|
150
|
+
*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.*
|
|
151
|
+
|
|
152
|
+
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
153
|
|
|
63
154
|
Street names, languages, address order, and postal components vary. ZAP uses the same generation function and encoding structure across its configured grids.
|
|
64
155
|
|
|
@@ -89,68 +180,6 @@ For navigation, use the original saved GPS coordinates—preferably the entrance
|
|
|
89
180
|
|
|
90
181
|
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
182
|
|
|
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
183
|
## Installation and local verification
|
|
155
184
|
|
|
156
185
|
After publication:
|
|
@@ -162,7 +191,7 @@ npm install @zukall/zap
|
|
|
162
191
|
Before publication, install the verified local package:
|
|
163
192
|
|
|
164
193
|
```sh
|
|
165
|
-
npm install /absolute/path/to/zukall-address-protocol/.artifacts/zukall-zap-0.2.
|
|
194
|
+
npm install /absolute/path/to/zukall-address-protocol/.artifacts/zukall-zap-0.2.2.tgz
|
|
166
195
|
```
|
|
167
196
|
|
|
168
197
|
Build and verify the source:
|
|
@@ -542,11 +571,11 @@ removed-option error.
|
|
|
542
571
|
```sh
|
|
543
572
|
npm login
|
|
544
573
|
npm run pack:check
|
|
545
|
-
npm publish ./.artifacts/zukall-zap-0.2.
|
|
574
|
+
npm publish ./.artifacts/zukall-zap-0.2.2.tgz --access public
|
|
546
575
|
```
|
|
547
576
|
|
|
548
577
|
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.
|
|
578
|
+
packing do not publish the package. Package version is `0.2.2`; current protocol
|
|
550
579
|
version is `2`, while preserved legacy results remain version `1`.
|
|
551
580
|
|
|
552
581
|
## License
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED