0
# Geographic Data
1

2
Location information including coordinates, places, and geographic boundaries for geo-tagged tweets.
3

4
## Capabilities
5

6
### Coordinates Class
7

8
Geographic coordinates representing the precise location where a tweet was posted.
9

10
```java { .api }
11
/**
12
 * Geographic location of tweet as geoJSON Point.
13
 * Coordinates are stored as [longitude, latitude] following geoJSON standard.
14
 */
15
public class Coordinates {
16

17
    /**
18
     * Default constructor
19
     */
20
    public Coordinates();
21

22
    /**
23
     * Gets the coordinate array [longitude, latitude]
24
     * @return Array of two doubles: [longitude, latitude]
25
     */
26
    public double[] getCoordinates();
27
    
28
    /**
29
     * Sets the coordinate array
30
     * @param coordinates - Array of [longitude, latitude]
31
     */
32
    public void setCoordinates(double[] coordinates);
33
    
34
    /**
35
     * Sets coordinates using individual longitude and latitude values
36
     * @param longitude - Longitude value
37
     * @param latitude - Latitude value
38
     */
39
    public void setCoordinates(double longitude, double latitude);
40
    
41
    /**
42
     * Gets the geometry type (always "point" for tweets)
43
     * @return String "point"
44
     */
45
    public String getType();
46
    
47
    /**
48
     * Returns formatted coordinate string
49
     * @return String representation of coordinates
50
     */
51
    public String toString();
52
}
53
```
54

55
### Places Class
56

57
Named locations that can be attached to tweets, representing specific venues, cities, or regions.
58

59
```java { .api }
60
/**
61
 * Named locations with coordinates that can be attached to tweets via place_id.
62
 * Includes detailed place information and geographic boundaries.
63
 */
64
public class Places {
65

66
    /**
67
     * Default constructor (initializes Attributes and BoundingBox)
68
     */
69
    public Places();
70

71
    /**
72
     * Gets the unique place ID
73
     * @return Place ID string
74
     */
75
    public String getId();
76
    
77
    /**
78
     * Sets the unique place ID
79
     * @param id - Place ID string
80
     */
81
    public void setId(String id);
82
    
83
    /**
84
     * Gets the place name
85
     * @return Short place name
86
     */
87
    public String getName();
88
    
89
    /**
90
     * Sets the place name
91
     * @param name - Short place name
92
     */
93
    public void setName(String name);
94
    
95
    /**
96
     * Gets the full place name including hierarchy
97
     * @return Full place name (e.g., "Manhattan, NY")
98
     */
99
    public String getFull_name();
100
    
101
    /**
102
     * Sets the full place name
103
     * @param full_name - Full place name
104
     */
105
    public void setFull_name(String full_name);
106
    
107
    /**
108
     * Gets the country name
109
     * @return Country name
110
     */
111
    public String getCountry();
112
    
113
    /**
114
     * Sets the country name
115
     * @param country - Country name
116
     */
117
    public void setCountry(String country);
118
    
119
    /**
120
     * Gets the ISO country code
121
     * @return Two-letter country code (e.g., "US", "GB")
122
     */
123
    public String getCountry_code();
124
    
125
    /**
126
     * Sets the ISO country code
127
     * @param country_code - Two-letter country code
128
     */
129
    public void setCountry_code(String country_code);
130
    
131
    /**
132
     * Gets the place type
133
     * @return Place type (e.g., "city", "neighborhood", "poi")
134
     */
135
    public String getPlace_type();
136
    
137
    /**
138
     * Sets the place type
139
     * @param place_type - Place type
140
     */
141
    public void setPlace_type(String place_type);
142
    
143
    /**
144
     * Gets the place URL for more information
145
     * @return URL string
146
     */
147
    public String getUrl();
148
    
149
    /**
150
     * Sets the place URL
151
     * @param url - URL string
152
     */
153
    public void setUrl(String url);
154
    
155
    /**
156
     * Gets additional place attributes (address, phone, etc.)
157
     * @return Attributes object containing detailed place information
158
     */
159
    public Attributes getAttributes();
160
    
161
    /**
162
     * Sets additional place attributes
163
     * @param attributes - Attributes object
164
     */
165
    public void setAttributes(Attributes attributes);
166
    
167
    /**
168
     * Gets the geographic boundary of the place
169
     * @return BoundingBox object defining place boundaries
170
     */
171
    public BoundingBox getBounding_box();
172
    
173
    /**
174
     * Sets the geographic boundary of the place
175
     * @param bounding_box - BoundingBox object
176
     */
177
    public void setBounding_box(BoundingBox bounding_box);
178
}
179
```
180

181
### Attributes Class
182

183
Detailed place attributes including address information and contact details.
184

185
```java { .api }
186
/**
187
 * Place attributes containing address and contact information.
188
 * Provides detailed metadata for place objects.
189
 */
190
public class Attributes {
191

192
    /**
193
     * Default constructor
194
     */
195
    public Attributes();
196

197
    /**
198
     * Gets the street address
199
     * @return Street address string
200
     */
201
    public String getStreet_address();
202
    
203
    /**
204
     * Sets the street address
205
     * @param street_address - Street address
206
     */
207
    public void setStreet_address(String street_address);
208
    
209
    /**
210
     * Gets the locality (city/town)
211
     * @return Locality string
212
     */
213
    public String getLocality();
214
    
215
    /**
216
     * Sets the locality
217
     * @param locality - Locality string
218
     */
219
    public void setLocality(String locality);
220
    
221
    /**
222
     * Gets the region (state/province)
223
     * @return Region string
224
     */
225
    public String getRegion();
226
    
227
    /**
228
     * Sets the region
229
     * @param region - Region string
230
     */
231
    public void setRegion(String region);
232
    
233
    /**
234
     * Gets the ISO3 country code
235
     * @return Three-letter country code
236
     */
237
    public String getIso3();
238
    
239
    /**
240
     * Sets the ISO3 country code
241
     * @param iso3 - Three-letter country code
242
     */
243
    public void setIso3(String iso3);
244
    
245
    /**
246
     * Gets the postal code
247
     * @return Postal code string
248
     */
249
    public String getPostal_code();
250
    
251
    /**
252
     * Sets the postal code
253
     * @param postal_code - Postal code
254
     */
255
    public void setPostal_code(String postal_code);
256
    
257
    /**
258
     * Gets the phone number
259
     * @return Phone number string
260
     */
261
    public String getPhone();
262
    
263
    /**
264
     * Sets the phone number
265
     * @param phone - Phone number
266
     */
267
    public void setPhone(String phone);
268
    
269
    /**
270
     * Gets the Twitter handle (always returns "twitter")
271
     * @return String "twitter"
272
     */
273
    public String getTwitter();
274
    
275
    /**
276
     * Gets the place website URL
277
     * @return Website URL string
278
     */
279
    public String getUrl();
280
    
281
    /**
282
     * Sets the place website URL
283
     * @param url - Website URL
284
     */
285
    public void setUrl(String url);
286
    
287
    /**
288
     * Gets the application ID that created this place
289
     * @return Application ID string (corresponds to API field "app:id")
290
     */
291
    public String getAppId();
292
    
293
    /**
294
     * Sets the application ID
295
     * @param appId - Application ID
296
     */
297
    public void setAppId(String appId);
298
}
299
```
300

301
### BoundingBox Class
302

303
Geographic boundaries defining the area containing a place entity.
304

305
```java { .api }
306
/**
307
 * Longitude/latitude points defining a box containing the Place entity.
308
 * Points are stored as [longitude, latitude] arrays following geoJSON standard.
309
 */
310
public class BoundingBox {
311

312
    /**
313
     * Default constructor
314
     */
315
    public BoundingBox();
316
    
317
    /**
318
     * Constructor with initial coordinate points
319
     * @param points - List of coordinate point arrays
320
     */
321
    public BoundingBox(List<double[]> points);
322

323
    /**
324
     * Gets the bounding box coordinates as nested lists
325
     * @return List containing a list of coordinate arrays
326
     */
327
    public List<List<double[]>> getCoordinates();
328
    
329
    /**
330
     * Sets the bounding box coordinates
331
     * @param coordinates - Nested list of coordinate arrays
332
     */
333
    public void setCoordinates(List<List<double[]>> coordinates);
334
    
335
    /**
336
     * Gets the geometry type (default is "Polygon")
337
     * @return String geometry type
338
     */
339
    public String getType();
340
    
341
    /**
342
     * Sets the geometry type
343
     * @param type - Geometry type string
344
     */
345
    public void setType(String type);
346
}
347
```
348

349
**Usage Examples:**
350

351
```java
352
import org.apache.flink.contrib.tweetinputformat.model.tweet.Tweet;
353
import org.apache.flink.contrib.tweetinputformat.model.tweet.Coordinates;
354
import org.apache.flink.contrib.tweetinputformat.model.places.Places;
355

356
// Process geo-tagged tweets
357
DataSet<Tweet> tweets = env.readFile(new SimpleTweetInputFormat(), "tweets.json");
358

359
// Filter tweets with coordinates
360
DataSet<Tweet> geoTweets = tweets.filter(tweet -> {
361
    Coordinates coords = tweet.getCoordinates();
362
    return coords != null && coords.getCoordinates() != null;
363
});
364

365
// Extract location information
366
DataSet<Tuple3<String, Double, Double>> tweetLocations = geoTweets.map(tweet -> {
367
    Coordinates coords = tweet.getCoordinates();
368
    double[] coordArray = coords.getCoordinates();
369
    return new Tuple3<>(
370
        tweet.getText(),
371
        coordArray[0], // longitude
372
        coordArray[1]  // latitude
373
    );
374
});
375

376
// Process place information
377
DataSet<String> placeTweets = tweets
378
    .filter(tweet -> tweet.getPlace() != null)
379
    .map(tweet -> {
380
        Places place = tweet.getPlace();
381
        return String.format("%s tweeted from %s, %s", 
382
            tweet.getUser().getScreen_name(),
383
            place.getName(),
384
            place.getCountry()
385
        );
386
    });
387
```
388

389
```java
390
// Detailed geographic analysis
391
Tweet tweet = new Tweet();
392
// Tweet populated by input format...
393

394
// Check for precise coordinates
395
Coordinates coords = tweet.getCoordinates();
396
if (coords != null && coords.getCoordinates() != null) {
397
    double[] coordArray = coords.getCoordinates();
398
    System.out.println("Precise location: " + coordArray[0] + ", " + coordArray[1]);
399
    System.out.println("Coordinates: " + coords.toString());
400
}
401

402
// Check for place information
403
Places place = tweet.getPlace();
404
if (place != null) {
405
    System.out.println("Place: " + place.getFull_name());
406
    System.out.println("Type: " + place.getPlace_type());
407
    System.out.println("Country: " + place.getCountry() + " (" + place.getCountry_code() + ")");
408
    
409
    // Access detailed attributes
410
    Attributes attrs = place.getAttributes();
411
    if (attrs.getStreet_address() != null) {
412
        System.out.println("Address: " + attrs.getStreet_address());
413
        System.out.println("City: " + attrs.getLocality());
414
        System.out.println("State: " + attrs.getRegion());
415
        System.out.println("Postal: " + attrs.getPostal_code());
416
    }
417
    
418
    if (attrs.getPhone() != null) {
419
        System.out.println("Phone: " + attrs.getPhone());
420
    }
421
    
422
    if (attrs.getUrl() != null) {
423
        System.out.println("Website: " + attrs.getUrl());
424
    }
425
}
426
```
427

428
```java
429
// Geographic aggregation and analysis
430
DataSet<Tweet> tweets = env.readFile(new SimpleTweetInputFormat(), "tweets.json");
431

432
// Count tweets by country
433
DataSet<Tuple2<String, Long>> tweetsByCountry = tweets
434
    .filter(tweet -> tweet.getPlace() != null)
435
    .map(tweet -> tweet.getPlace().getCountry())
436
    .groupBy(country -> country)
437
    .reduceGroup(countryGroup -> {
438
        String country = null;
439
        long count = 0;
440
        for (String c : countryGroup) {
441
            country = c;
442
            count++;
443
        }
444
        return new Tuple2<>(country, count);
445
    });
446

447
// Find tweets within a geographic region
448
DataSet<Tweet> regionTweets = tweets.filter(tweet -> {
449
    Coordinates coords = tweet.getCoordinates();
450
    if (coords != null && coords.getCoordinates() != null) {
451
        double[] coordArray = coords.getCoordinates();
452
        double longitude = coordArray[0];
453
        double latitude = coordArray[1];
454
        
455
        // Example: tweets within New York City area
456
        return longitude >= -74.25 && longitude <= -73.70 &&
457
               latitude >= 40.49 && latitude <= 40.92;
458
    }
459
    return false;
460
});
461
```
462

463
**Key Features:**
464

465
- **GeoJSON Standard**: Coordinates follow geoJSON format with longitude first, then latitude
466
- **Hierarchical Places**: Places include name, full name, and geographic hierarchy
467
- **Detailed Attributes**: Address, phone, and contact information for places
468
- **Bounding Boxes**: Geographic boundaries for place areas
469
- **Coordinate Precision**: Support for precise GPS coordinates from mobile devices
470
- **Place Types**: Different types of places (city, neighborhood, POI, etc.)
471
- **Country Codes**: Both ISO2 and ISO3 country code support