0
# Format Conversion
1

2
The Elasticsearch Geo library provides comprehensive support for converting geometries to and from standard geospatial formats including Well-Known Text (WKT), Well-Known Binary (WKB), and GeoHash. These utilities enable interoperability with other geospatial systems and efficient serialization.
3

4
## Capabilities
5

6
### Well-Known Text (WKT) Format
7
Convert geometries to and from the industry-standard Well-Known Text format for human-readable representation.
8

9
```java { .api }
10
/**
11
 * Converts a geometry to WKT string representation
12
 * @param geometry the geometry to convert
13
 * @return WKT string representation
14
 */
15
public static String toWKT(Geometry geometry)
16

17
/**
18
 * Parses a WKT string to create a geometry object
19
 * @param validator geometry validator to apply
20
 * @param coerce whether to coerce invalid geometries (e.g., auto-close polygons)
21
 * @param wkt the WKT string to parse
22
 * @return parsed geometry object
23
 * @throws IOException if parsing fails
24
 * @throws ParseException if WKT format is invalid
25
 */
26
public static Geometry fromWKT(GeometryValidator validator, boolean coerce, String wkt) 
27
    throws IOException, ParseException
28

29

30
// WKT format constants
31
public static final String EMPTY = "EMPTY";
32
public static final String SPACE = " ";
33
public static final String LPAREN = "(";
34
public static final String RPAREN = ")";
35
public static final String COMMA = ",";
36
public static final String NAN = "NaN";
37
public static final String Z = "Z";
38
public static final String M = "M";
39
public static final int MAX_NESTED_DEPTH = 1000;
40

41
// Example WKT formats:
42
// Point: "POINT(-73.935242 40.730610)"
43
// Circle: "CIRCLE(-73.935242 40.730610 1000.0)"  
44
// Polygon: "POLYGON((-74.0 40.7,-73.9 40.7,-73.9 40.8,-74.0 40.8,-74.0 40.7))"
45
// MultiPoint: "MULTIPOINT(-73.935242 40.730610,-73.945242 40.740610)"
46
```
47

48
### Well-Known Binary (WKB) Format
49
Convert geometries to binary format for efficient storage and transmission.
50

51
```java { .api }
52
/**
53
 * Converts a geometry to Well-Known Binary format
54
 * @param geometry the geometry to convert
55
 * @param byteOrder byte order for binary encoding (BIG_ENDIAN or LITTLE_ENDIAN)
56
 * @return byte array containing WKB representation
57
 */
58
public static byte[] toWKB(Geometry geometry, ByteOrder byteOrder)
59

60
/**
61
 * Parses Well-Known Binary data to create a geometry object
62
 * @param validator geometry validator to apply
63
 * @param coerce whether to coerce invalid geometries
64
 * @param wkb byte array containing WKB data
65
 * @return parsed geometry object
66
 */
67
public static Geometry fromWKB(GeometryValidator validator, boolean coerce, byte[] wkb)
68

69
/**
70
 * Parses Well-Known Binary data to create a geometry object
71
 * @param validator geometry validator to apply
72
 * @param coerce whether to coerce invalid geometries  
73
 * @param wkb byte array containing WKB data
74
 * @param offset starting position in byte array
75
 * @param length number of bytes to read
76
 * @return parsed geometry object
77
 */
78
public static Geometry fromWKB(GeometryValidator validator, boolean coerce, byte[] wkb, int offset, int length)
79

80
// Usage example:
81
import java.nio.ByteOrder;
82

83
Point point = new Point(-73.935242, 40.730610);
84
byte[] wkbData = WellKnownBinary.toWKB(point, ByteOrder.BIG_ENDIAN);
85

86
// WKB format is binary and not human-readable
87
// Use for efficient storage and network transmission
88
```
89

90
### GeoHash Encoding and Decoding
91
Convert between coordinates and GeoHash strings for spatial indexing and proximity searches.
92

93
```java { .api }
94
/**
95
 * Maximum precision level for geohash strings
96
 */
97
public static final int PRECISION = 12;
98

99
/**
100
 * Converts geohash string to Point geometry
101
 * @param geohash the geohash string
102
 * @return Point representing geohash center
103
 * @throws IllegalArgumentException if geohash is invalid
104
 */
105
public static Point toPoint(String geohash)
106

107
/**
108
 * Computes bounding box for a geohash cell
109
 * @param geohash the geohash string
110
 * @return Rectangle representing geohash bounds
111
 */
112
public static Rectangle toBoundingBox(String geohash)
113

114
/**
115
 * Encodes coordinates to geohash string with default precision
116
 * @param lon longitude in decimal degrees
117
 * @param lat latitude in decimal degrees
118
 * @return geohash string at precision 12
119
 */
120
public static String stringEncode(double lon, double lat)
121

122
/**
123
 * Encodes coordinates to geohash string with specified precision
124
 * @param lon longitude in decimal degrees
125
 * @param lat latitude in decimal degrees
126
 * @param level precision level (1-12)
127
 * @return geohash string at specified precision
128
 */
129
public static String stringEncode(double lon, double lat, int level)
130

131
/**
132
 * Encodes coordinates to geohash long format for efficient storage
133
 * @param lon longitude in decimal degrees
134
 * @param lat latitude in decimal degrees  
135
 * @param level precision level (1-12)
136
 * @return geohash as long value with embedded level
137
 */
138
public static long longEncode(double lon, double lat, int level)
139

140
/**
141
 * Converts geohash string to long format
142
 * @param hash geohash string
143
 * @return geohash as long value
144
 */
145
public static long longEncode(String hash)
146

147
/**
148
 * Converts long format geohash to string
149
 * @param geoHashLong geohash in long format
150
 * @return geohash string
151
 */
152
public static String stringEncode(long geoHashLong)
153

154
/**
155
 * Encodes geohash to morton long value for spatial operations
156
 * @param hash geohash string
157
 * @return morton encoded value
158
 * @throws IllegalArgumentException if geohash is empty or contains invalid characters
159
 */
160
public static long mortonEncode(String hash)
161
```
162

163
### GeoHash Spatial Operations
164
Perform spatial queries and neighbor calculations using geohash encoding.
165

166
```java { .api }
167
/**
168
 * Gets all child geohashes one level below the base geohash
169
 * @param baseGeohash parent geohash
170
 * @return array of child geohashes (sorted)
171
 */
172
public static String[] getSubGeohashes(String baseGeohash)
173

174
/**
175
 * Gets all neighbor geohashes surrounding the given geohash
176
 * @param geohash center geohash
177
 * @return collection of neighboring geohashes (up to 8 neighbors)
178
 */
179
public static Collection<? extends CharSequence> getNeighbors(String geohash)
180

181
/**
182
 * Adds neighbor geohashes to an existing collection
183
 * @param geohash center geohash
184
 * @param neighbors collection to add neighbors to
185
 * @return the provided collection with neighbors added
186
 */
187
public static <E extends Collection<? super String>> E addNeighbors(String geohash, E neighbors)
188

189
/**
190
 * Gets a specific neighbor in a given direction
191
 * @param geohash center geohash
192
 * @param level precision level
193
 * @param dx horizontal offset (-1, 0, or +1)
194
 * @param dy vertical offset (-1, 0, or +1)
195
 * @return neighbor geohash or null if at boundary
196
 */
197
public static String getNeighbor(String geohash, int level, int dx, int dy)
198

199
/**
200
 * Gets approximate longitude width for geohash precision
201
 * @param precision geohash precision level (1-12)
202
 * @return width in degrees
203
 */
204
public static double lonWidthInDegrees(int precision)
205

206
/**
207
 * Gets approximate latitude height for geohash precision  
208
 * @param precision geohash precision level (1-12)
209
 * @return height in degrees
210
 */
211
public static double latHeightInDegrees(int precision)
212
```
213

214
### Coordinate Encoding and Decoding
215
Low-level utilities for encoding coordinates to integer representations.
216

217
```java { .api }
218
/**
219
 * Encodes latitude to integer representation
220
 * @param latitude latitude in decimal degrees
221
 * @return encoded integer value
222
 */
223
public static int encodeLatitude(double latitude)
224

225
/**
226
 * Encodes longitude to integer representation
227
 * @param longitude longitude in decimal degrees
228
 * @return encoded integer value
229
 */
230
public static int encodeLongitude(double longitude)
231

232
/**
233
 * Decodes latitude from geohash string
234
 * @param geohash geohash string
235
 * @return latitude in decimal degrees
236
 */
237
public static double decodeLatitude(String geohash)
238

239
/**
240
 * Decodes longitude from geohash string
241
 * @param geohash geohash string
242
 * @return longitude in decimal degrees
243
 */
244
public static double decodeLongitude(String geohash)
245

246
/**
247
 * Decodes latitude from morton encoded value
248
 * @param hash morton encoded hash
249
 * @return latitude in decimal degrees
250
 */
251
public static double decodeLatitude(long hash)
252

253
/**
254
 * Decodes longitude from morton encoded value
255
 * @param hash morton encoded hash
256
 * @return longitude in decimal degrees
257
 */
258
public static double decodeLongitude(long hash)
259
```
260

261
## Usage Examples
262

263
### WKT Conversion Examples
264

265
```java
266
import org.elasticsearch.geometry.*;
267
import org.elasticsearch.geometry.utils.WellKnownText;
268
import org.elasticsearch.geometry.utils.StandardValidator;
269

270
// Convert geometry to WKT
271
Point point = new Point(-73.935242, 40.730610);
272
String wkt = WellKnownText.toWKT(point);
273
// Result: "POINT(-73.935242 40.730610)"
274

275
Circle circle = new Circle(-73.935242, 40.730610, 1000.0);
276
String circleWkt = WellKnownText.toWKT(circle);
277
// Result: "CIRCLE(-73.935242 40.730610 1000.0)"
278

279
// Parse WKT to geometry
280
GeometryValidator validator = StandardValidator.instance(false);
281
String wktString = "POINT(-73.935242 40.730610)";
282
Geometry parsed = WellKnownText.fromWKT(validator, false, wktString);
283

284
// Parse with coercion (auto-close polygons)
285
String polygonWkt = "POLYGON((-74.0 40.7,-73.9 40.7,-73.9 40.8,-74.0 40.8))"; // missing closing point
286
Geometry coerced = WellKnownText.fromWKT(validator, true, polygonWkt);
287
```
288

289
### WKB Conversion Examples
290

291
```java
292
import org.elasticsearch.geometry.utils.WellKnownBinary;
293
import java.nio.ByteOrder;
294

295
// Convert to binary format
296
Point point = new Point(-73.935242, 40.730610);
297
byte[] wkbData = WellKnownBinary.toWKB(point, ByteOrder.BIG_ENDIAN);
298

299
// Parse binary data back to geometry
300
GeometryValidator validator = StandardValidator.instance(false);
301
Geometry parsedFromWkb = WellKnownBinary.fromWKB(validator, false, wkbData);
302

303
// Convert back to WKT if needed
304
String wktFromWkb = WellKnownText.toWKT(parsedFromWkb);
305
```
306

307
### GeoHash Examples
308

309
```java
310
import org.elasticsearch.geometry.utils.Geohash;
311
import java.util.Collection;
312

313
// Encode coordinates to geohash
314
double lon = -73.935242;
315
double lat = 40.730610; 
316
String geohash = Geohash.stringEncode(lon, lat, 12); // precision 12
317
// Result: "dr5regw3r5r3"
318

319
// Decode geohash to point
320
Point center = Geohash.toPoint(geohash);
321
Rectangle bounds = Geohash.toBoundingBox(geohash);
322

323
// Get geohash neighbors
324
Collection<? extends CharSequence> neighbors = Geohash.getNeighbors(geohash);
325
// Returns up to 8 surrounding geohashes
326

327
// Get specific neighbor (east)
328
String eastNeighbor = Geohash.getNeighbor(geohash, geohash.length(), 1, 0);
329

330
// Get child geohashes
331
String[] children = Geohash.getSubGeohashes(geohash);
332
// Returns 32 child geohashes one level more precise
333

334
// Check precision properties
335
double lonWidth = Geohash.lonWidthInDegrees(12); // longitude width at precision 12
336
double latHeight = Geohash.latHeightInDegrees(12); // latitude height at precision 12
337

338
// Long format encoding for efficient storage
339
long longGeohash = Geohash.longEncode(lon, lat, 12);
340
String backToString = Geohash.stringEncode(longGeohash);
341
```
342

343
### Format Integration Example
344

345
```java
346
// Complete workflow: Geometry -> WKT -> Parse -> GeoHash -> Bounds
347
Point originalPoint = new Point(-73.935242, 40.730610);
348

349
// Convert to WKT
350
String wkt = WellKnownText.toWKT(originalPoint);
351

352
// Parse back from WKT
353
GeometryValidator validator = StandardValidator.instance(false);
354
Point parsedPoint = (Point) WellKnownText.fromWKT(validator, false, wkt);
355

356
// Convert to geohash
357
String geohash = Geohash.stringEncode(parsedPoint.getX(), parsedPoint.getY(), 10);
358

359
// Get bounding box for geohash cell
360
Rectangle geohashBounds = Geohash.toBoundingBox(geohash);
361

362
// Convert bounds to WKT
363
String boundsWkt = WellKnownText.toWKT(geohashBounds);
364
// Result: "BBOX(-73.9404296875 -73.9349365234375 40.7312011719 40.728759765625)"
365
```