0
# Geographic Data
1

2
Geographic information including coordinates, places, and location metadata associated with tweets.
3

4
## Capabilities
5

6
### Coordinates
7

8
GeoJSON-formatted coordinate information representing the precise geographic location where a tweet was posted.
9

10
```java { .api }
11
/**
12
 * Represents geographic coordinates of a tweet in GeoJSON format.
13
 * Contains longitude and latitude coordinates as reported by the user or client.
14
 */
15
public class Coordinates {
16
    
17
    /**
18
     * Default constructor that initializes coordinate type as "point".
19
     */
20
    public Coordinates();
21
    
22
    /**
23
     * Get the coordinate array [longitude, latitude].
24
     * @return Array containing [longitude, latitude] as doubles
25
     */
26
    public double[] getCoordinates();
27
    
28
    /**
29
     * Set the coordinate array [longitude, latitude].
30
     * @param coordinates Array containing [longitude, latitude] as doubles
31
     */
32
    public void setCoordinates(double[] coordinates);
33
    
34
    /**
35
     * Set coordinates using individual longitude and latitude values.
36
     * @param longitude Longitude value (first in GeoJSON format)
37
     * @param latitude Latitude value (second in GeoJSON format)
38
     */
39
    public void setCoordinates(double longitude, double latitude);
40
    
41
    /**
42
     * Get the coordinate type (always "point" for Twitter coordinates).
43
     * @return Coordinate type string
44
     */
45
    public String getType();
46
    
47
    /**
48
     * String representation of coordinates for debugging.
49
     * @return Human-readable coordinate string
50
     */
51
    public String toString();
52
}
53
```
54

55
### Places
56

57
Named location information representing specific places associated with tweets, providing context beyond precise coordinates.
58

59
```java { .api }
60
/**
61
 * Represents named locations with geographic context.
62
 * Provides place information that can be attached to tweets by specifying a place_id.
63
 */
64
public class Places {
65
    
66
    /**
67
     * Default constructor that initializes attributes and bounding box.
68
     */
69
    public Places();
70
    
71
    /**
72
     * Get the unique identifier for this place.
73
     * @return Place ID string
74
     */
75
    public String getId();
76
    
77
    /**
78
     * Set the unique identifier for this place.
79
     * @param id Place ID string
80
     */
81
    public void setId(String id);
82
    
83
    /**
84
     * Get the short name of this place.
85
     * @return Place name
86
     */
87
    public String getName();
88
    
89
    /**
90
     * Set the short name of this place.
91
     * @param name Place name
92
     */
93
    public void setName(String name);
94
    
95
    /**
96
     * Get the full descriptive name of this place.
97
     * @return Full place name
98
     */
99
    public String getFull_name();
100
    
101
    /**
102
     * Set the full descriptive name of this place.
103
     * @param full_name Full place name
104
     */
105
    public void setFull_name(String full_name);
106
    
107
    /**
108
     * Get the country name for this place.
109
     * @return Country name
110
     */
111
    public String getCountry();
112
    
113
    /**
114
     * Set the country name for this place.
115
     * @param country Country name
116
     */
117
    public void setCountry(String country);
118
    
119
    /**
120
     * Get the ISO 3166-1 alpha-2 country code.
121
     * @return Two-letter country code
122
     */
123
    public String getCountry_code();
124
    
125
    /**
126
     * Set the ISO 3166-1 alpha-2 country code.
127
     * @param country_code Two-letter country code
128
     */
129
    public void setCountry_code(String country_code);
130
    
131
    /**
132
     * Get the type of place (city, neighborhood, poi, etc.).
133
     * @return Place type string
134
     */
135
    public String getPlace_type();
136
    
137
    /**
138
     * Set the type of place (city, neighborhood, poi, etc.).
139
     * @param place_type Place type string
140
     */
141
    public void setPlace_type(String place_type);
142
    
143
    /**
144
     * Get the URL for more information about this place.
145
     * @return Place URL
146
     */
147
    public String getUrl();
148
    
149
    /**
150
     * Set the URL for more information about this place.
151
     * @param url Place URL
152
     */
153
    public void setUrl(String url);
154
    
155
    /**
156
     * Get additional attributes for this place.
157
     * @return Attributes object containing detailed place information
158
     */
159
    public Attributes getAttributes();
160
    
161
    /**
162
     * Set additional attributes for this place.
163
     * @param attributes Attributes object containing detailed place information
164
     */
165
    public void setAttributes(Attributes attributes);
166
    
167
    /**
168
     * Get the bounding box that encompasses this place.
169
     * @return BoundingBox object defining geographic boundaries
170
     */
171
    public BoundingBox getBounding_box();
172
    
173
    /**
174
     * Set the bounding box that encompasses this place.
175
     * @param bounding_box BoundingBox object defining geographic boundaries
176
     */
177
    public void setBounding_box(BoundingBox bounding_box);
178
}
179
```
180

181
### Attributes
182

183
Additional detailed attributes providing extended information about places including address components and contact information.
184

185
```java { .api }
186
/**
187
 * Additional attributes for places providing detailed location information.
188
 * Contains address components, contact information, and other place metadata.
189
 */
190
public class Attributes {
191
    
192
    /**
193
     * Default constructor.
194
     */
195
    public Attributes();
196
    
197
    /**
198
     * Get the street address for this place.
199
     * @return Street address
200
     */
201
    public String getStreet_address();
202
    
203
    /**
204
     * Set the street address for this place.
205
     * @param street_address Street address
206
     */
207
    public void setStreet_address(String street_address);
208
    
209
    /**
210
     * Get the locality (city/town) for this place.
211
     * @return Locality name
212
     */
213
    public String getLocality();
214
    
215
    /**
216
     * Set the locality (city/town) for this place.
217
     * @param locality Locality name
218
     */
219
    public void setLocality(String locality);
220
    
221
    /**
222
     * Get the region (state/province) for this place.
223
     * @return Region name
224
     */
225
    public String getRegion();
226
    
227
    /**
228
     * Set the region (state/province) for this place.
229
     * @param region Region name
230
     */
231
    public void setRegion(String region);
232
    
233
    /**
234
     * Get the ISO 3166-1 alpha-3 country code.
235
     * @return Three-letter country code
236
     */
237
    public String getIso3();
238
    
239
    /**
240
     * Set the ISO 3166-1 alpha-3 country code.
241
     * @param iso3 Three-letter country code
242
     */
243
    public void setIso3(String iso3);
244
    
245
    /**
246
     * Get the postal code for this place.
247
     * @return Postal code
248
     */
249
    public String getPostal_code();
250
    
251
    /**
252
     * Set the postal code for this place.
253
     * @param postal_code Postal code
254
     */
255
    public void setPostal_code(String postal_code);
256
    
257
    /**
258
     * Get the phone number for this place.
259
     * @return Phone number
260
     */
261
    public String getPhone();
262
    
263
    /**
264
     * Set the phone number for this place.
265
     * @param phone Phone number
266
     */
267
    public void setPhone(String phone);
268
    
269
    /**
270
     * Get the URL for this place.
271
     * @return Place URL
272
     */
273
    public String getUrl();
274
    
275
    /**
276
     * Set the URL for this place.
277
     * @param url Place URL
278
     */
279
    public void setUrl(String url);
280
    
281
    /**
282
     * Get the application ID associated with this place.
283
     * @return Application ID
284
     */
285
    public String getAppId();
286
    
287
    /**
288
     * Set the application ID associated with this place.
289
     * @param appId Application ID
290
     */
291
    public void setAppId(String appId);
292
}
293
```
294

295
### BoundingBox
296

297
Geographic boundaries defining the area encompassed by a place, represented as coordinate bounds.
298

299
```java { .api }
300
/**
301
 * Represents geographic boundaries for places as coordinate bounds.
302
 * Defines the rectangular area that encompasses a place.
303
 */
304
public class BoundingBox {
305
    
306
    /**
307
     * Default constructor.
308
     */
309
    public BoundingBox();
310
    
311
    /**
312
     * Constructor with list of coordinate points.
313
     * @param points List of coordinate points [longitude, latitude]
314
     */
315
    public BoundingBox(List<double[]> points);
316
    
317
    /**
318
     * Get the bounding box type (usually "Polygon").
319
     * @return Bounding box type
320
     */
321
    public String getType();
322
    
323
    /**
324
     * Set the bounding box type (usually "Polygon").
325
     * @param type Bounding box type
326
     */
327
    public void setType(String type);
328
    
329
    /**
330
     * Get the coordinate list defining the bounding box.
331
     * @return List of coordinate point lists
332
     */
333
    public List<List<double[]>> getCoordinates();
334
    
335
    /**
336
     * Set the coordinate list defining the bounding box.
337
     * @param coordinates List of coordinate point lists
338
     */
339
    public void setCoordinates(List<List<double[]>> coordinates);
340
}
341
```
342

343
**Usage Examples:**
344

345
```java
346
import org.apache.flink.contrib.tweetinputformat.model.tweet.Coordinates;
347
import org.apache.flink.contrib.tweetinputformat.model.places.*;
348
import java.util.List;
349

350
// Process geographic information
351
Tweet tweet = // ... get tweet
352

353
// Check for precise coordinates
354
Coordinates coords = tweet.getCoordinates();
355
if (coords != null) {
356
    double[] coordinates = coords.getCoordinates();
357
    double longitude = coordinates[0];
358
    double latitude = coordinates[1];
359
    
360
    System.out.printf("Tweet location: %.6f, %.6f%n", longitude, latitude);
361
    System.out.println("Coordinate type: " + coords.getType());
362
}
363

364
// Check for place information
365
Places place = tweet.getPlace();
366
if (place != null) {
367
    System.out.println("Place: " + place.getName());
368
    System.out.println("Full name: " + place.getFull_name());
369
    System.out.println("Country: " + place.getCountry() + " (" + place.getCountry_code() + ")");
370
    System.out.println("Place type: " + place.getPlace_type());
371
    
372
    // Access detailed attributes
373
    Attributes attributes = place.getAttributes();
374
    if (!attributes.getStreet_address().isEmpty()) {
375
        System.out.println("Address: " + attributes.getStreet_address());
376
        System.out.println("City: " + attributes.getLocality());
377
        System.out.println("Region: " + attributes.getRegion());
378
        System.out.println("Postal code: " + attributes.getPostal_code());
379
    }
380
    
381
    if (!attributes.getPhone().isEmpty()) {
382
        System.out.println("Phone: " + attributes.getPhone());
383
    }
384
    
385
    if (!attributes.getUrl().isEmpty()) {
386
        System.out.println("URL: " + attributes.getUrl());
387
    }
388
    
389
    // Access bounding box
390
    BoundingBox bbox = place.getBounding_box();
391
    if (bbox != null) {
392
        System.out.println("Bounding box type: " + bbox.getType());
393
        // Process bounding box coordinates as needed...
394
    }
395
}
396

397
// Determine location availability
398
boolean hasLocation = (coords != null) || (place != null);
399
if (hasLocation) {
400
    System.out.println("Tweet has geographic information");
401
} else {
402
    System.out.println("No geographic information available");
403
}
404
```
405

406
## Geographic Analysis Patterns
407

408
Common patterns for analyzing geographic data in stream processing:
409

410
```java
411
// Filter tweets with precise coordinates
412
tweets.filter(tweet -> tweet.getCoordinates() != null)
413
      .map(tweet -> {
414
          double[] coords = tweet.getCoordinates().getCoordinates();
415
          return new GeoTweet(
416
              tweet.getId_str(),
417
              tweet.getText(),
418
              coords[0], // longitude
419
              coords[1]  // latitude
420
          );
421
      });
422

423
// Filter tweets by country
424
tweets.filter(tweet -> {
425
    Places place = tweet.getPlace();
426
    return place != null && "US".equals(place.getCountry_code());
427
});
428

429
// Extract place types
430
tweets.filter(tweet -> tweet.getPlace() != null)
431
      .map(tweet -> tweet.getPlace().getPlace_type())
432
      .countByValue();
433

434
// Geographic clustering by place names
435
tweets.filter(tweet -> tweet.getPlace() != null)
436
      .map(tweet -> tweet.getPlace().getFull_name())
437
      .countByValue();
438

439
// Region-based analysis
440
tweets.filter(tweet -> {
441
    Places place = tweet.getPlace();
442
    return place != null && place.getAttributes() != null;
443
}).map(tweet -> {
444
    Attributes attrs = tweet.getPlace().getAttributes();
445
    return new RegionTweet(
446
        tweet.getId_str(),
447
        attrs.getLocality(),
448
        attrs.getRegion(),
449
        tweet.getPlace().getCountry_code()
450
    );
451
});
452

453
// Distance calculation from reference point
454
double refLon = -74.0060;  // New York City
455
double refLat = 40.7128;
456

457
tweets.filter(tweet -> tweet.getCoordinates() != null)
458
      .map(tweet -> {
459
          double[] coords = tweet.getCoordinates().getCoordinates();
460
          double distance = calculateDistance(refLat, refLon, coords[1], coords[0]);
461
          return new DistanceTweet(tweet.getId_str(), distance);
462
      });
463
```
464

465
## Coordinate System Notes
466

467
Important considerations for working with Twitter coordinates:
468

469
- **GeoJSON Format**: Coordinates are in [longitude, latitude] order (longitude first)
470
- **Coordinate System**: Uses WGS84 coordinate system (EPSG:4326)
471
- **Precision**: Double precision floating point coordinates
472
- **Null Handling**: Always check for null coordinates and places before processing
473

474
```java
475
// Safe coordinate extraction
476
public static class GeoUtils {
477
    
478
    public static double[] extractCoordinates(Tweet tweet) {
479
        Coordinates coords = tweet.getCoordinates();
480
        return coords != null ? coords.getCoordinates() : null;
481
    }
482
    
483
    public static String extractCountryCode(Tweet tweet) {
484
        Places place = tweet.getPlace();
485
        return place != null ? place.getCountry_code() : null;
486
    }
487
    
488
    public static double calculateDistance(double lat1, double lon1, double lat2, double lon2) {
489
        // Haversine formula implementation
490
        final double R = 6371; // Earth's radius in kilometers
491
        
492
        double dLat = Math.toRadians(lat2 - lat1);
493
        double dLon = Math.toRadians(lon2 - lon1);
494
        
495
        double a = Math.sin(dLat/2) * Math.sin(dLat/2) +
496
                  Math.cos(Math.toRadians(lat1)) * Math.cos(Math.toRadians(lat2)) *
497
                  Math.sin(dLon/2) * Math.sin(dLon/2);
498
        
499
        double c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
500
        
501
        return R * c;
502
    }
503
}
504
```