## section-place

section-place

## Functions

void | flickcurl_free_place ()
void | flickcurl_free_places ()
int | flickcurl_place_type_to_id ()
void | flickcurl_free_place_type_infos ()
flickcurl_place_type | flickcurl_get_place_type_by_label ()
const char * | flickcurl_get_place_type_label ()
flickcurl_place ** | flickcurl_places_find ()
flickcurl_place * | flickcurl_places_findByLatLon ()
flickcurl_place ** | flickcurl_places_forUser ()
flickcurl_place ** | flickcurl_places_getChildrenWithPhotosPublic ()
flickcurl_place ** | flickcurl_places_getChildrenWithPhotosPublic2 ()
flickcurl_place * | flickcurl_places_getInfo ()
flickcurl_place * | flickcurl_places_getInfo2 ()
flickcurl_place * | flickcurl_places_getInfoByUrl ()
flickcurl_place_type_info ** | flickcurl_places_getPlaceTypes ()
flickcurl_shapedata ** | flickcurl_places_getShapeHistory ()
flickcurl_place ** | flickcurl_places_getTopPlacesList ()
flickcurl_place_type | flickcurl_place_id_to_type ()
flickcurl_place ** | flickcurl_places_placesForBoundingBox ()
flickcurl_place ** | flickcurl_places_placesForContacts ()
flickcurl_place ** | flickcurl_places_placesForUser ()
int | flickcurl_places_placesForTags ()
flickcurl_place * | flickcurl_places_resolvePlaceId ()
flickcurl_place * | flickcurl_places_resolvePlaceURL ()
flickcurl_tag ** | flickcurl_places_tagsForPlace ()

## Types and Values

| flickcurl_place
enum | flickcurl_place_type
| flickcurl_place_type_info

## Description

## Functions

### flickcurl_free_place ()

    void
    flickcurl_free_place (flickcurl_place *place);

Destructor for place object

#### Parameters

place | place object |

### flickcurl_free_places ()

    void
    flickcurl_free_places (flickcurl_place **places_object);

Destructor for array of place object

#### Parameters

places_object | place object array |

### flickcurl_place_type_to_id ()

    int
    flickcurl_place_type_to_id (flickcurl_place_type place_type);

Turn a place type into a place ID

#### Parameters

place_type | place type |

#### Returns

place ID for type or <0 on failure

### flickcurl_free_place_type_infos ()

    void
    flickcurl_free_place_type_infos (flickcurl_place_type_info **ptis_object);

Destructor for place type info list

#### Parameters

ptis_object | list of place type info |

### flickcurl_get_place_type_by_label ()

    flickcurl_place_type
    flickcurl_get_place_type_by_label (const char *place_label);

Get a place type by label

#### Parameters

place_label | place type |

#### Returns

place type

### flickcurl_get_place_type_label ()

    const char *
    flickcurl_get_place_type_label (flickcurl_place_type place_type);

Get label for a place type

#### Parameters

place_type | place type |

#### Returns

label string or NULL if none valid

### flickcurl_places_find ()

    flickcurl_place **
    flickcurl_places_find (flickcurl *fc,
                           const char *query);

Return a list of place IDs for a query string.

The flickr.places.find method is NOT a geocoder. It will round up to the nearest place type to which place IDs apply. For example, if you pass it a street level address it will return the city that contains the address rather than the street, or building, itself.

This API announced 2008-01-18 http://tech.groups.yahoo.com/group/yws-flickr/message/3716

Implements flickr.places.find (1.1)

#### Parameters

fc | flickcurl context |
query | The query string to use for place ID lookups |

#### Returns

array of places or NULL on failure

### flickcurl_places_findByLatLon ()

    flickcurl_place *
    flickcurl_places_findByLatLon (flickcurl *fc,
                                   double lat,
                                   double lon,
                                   int accuracy);

Return a place ID for a latitude, longitude and accuracy triple.

The flickr.places.findByLatLon method is not meant to be a (reverse) geocoder in the traditional sense. It is designed to allow users to find photos for "places" and will round up to the nearest place type to which corresponding place IDs apply.

This API announced 2008-01-23 http://tech.groups.yahoo.com/group/yws-flickr/message/3735

Implements flickr.places.findByLatLon (1.1)

#### Parameters

fc | flickcurl context |
lat | The latitude whose valid range is -90 to 90. Anything more than 4 decimal places will be truncated. |
lon | The longitude whose valid range is -180 to 180. Anything more than 4 decimal places will be truncated. |
accuracy | Recorded accuracy level of the location information. World level is 1, Country is ~3, Region ~6, City ~11, Street ~16. Current range is 1-16. The default is 16. |

#### Returns

non-0 on failure

### flickcurl_places_forUser ()

    flickcurl_place **
    flickcurl_places_forUser (flickcurl *fc,
                              flickcurl_place_type place_type,
                              int woe_id,
                              const char *place_id,
                              int threshold);

`flickcurl_places_forUser` is deprecated and should not be used in newly-written code.

Return a list of the top 100 unique places clustered by a given place type for a user.

`deprecated` : Use `flickcurl_places_placesForUser()`

#### Parameters

fc | flickcurl context |
place_type | A specific place type to cluster photos by. Valid places types are neighbourhood, locality, region or country |
woe_id | A Where on Earth ID to use to filter photo clusters. (or <0) |
place_id | A Places ID to use to filter photo clusters. (or NULL) |
threshold | The minimum number of photos that a place type must have to be included. If the number of photos is lowered then the parent place type for that place will be used. (or <0) |

#### Returns

non-0 on failure

### flickcurl_places_getChildrenWithPhotosPublic ()

    flickcurl_place **
    flickcurl_places_getChildrenWithPhotosPublic
                                   (flickcurl *fc,
                                    const char *place_id,
                                    const char *woe_id);

`flickcurl_places_getChildrenWithPhotosPublic` is deprecated and should not be used in newly-written code.

Return a list of locations with public photos that are parented by a Where on Earth (WOE) or Places ID.

Implements flickr.places.getChildrenWithPhotosPublic (1.7)

`deprecated` : Replaced by `flickcurl_places_getChildrenWithPhotosPublic2()` with integer woe_id argument.

#### Parameters

fc | flickcurl context |
place_id | A Places ID. (While optional, you must pass either a valid Places ID or a WOE ID.) (or NULL) |
woe_id | A Where On Earth (WOE) ID. (While optional, you must pass either a valid Places ID or a WOE ID.) (or NULL) |

#### Returns

array of places or NULL on failure

### flickcurl_places_getChildrenWithPhotosPublic2 ()

    flickcurl_place **
    flickcurl_places_getChildrenWithPhotosPublic2
                                   (flickcurl *fc,
                                    const char *place_id,
                                    int woe_id);

Return a list of locations with public photos that are parented by a Where on Earth (WOE) or Places ID.

You must pass either a valid Places ID or a WOE ID.

Replaces `flickcurl_places_getChildrenWithPhotosPublic()` with integer `woe_id` arg.

#### Parameters

fc | flickcurl context |
place_id | A Places ID (or NULL) |
woe_id | A Where On Earth (WOE) ID (or <0) |

#### Returns

array of places or NULL on failure

### flickcurl_places_getInfo ()

    flickcurl_place *
    flickcurl_places_getInfo (flickcurl *fc,
                              const char *place_id,
                              const char *woe_id);

`flickcurl_places_getInfo` is deprecated and should not be used in newly-written code.

Get information about a place.

While optional, you must pass either a valid Places ID or a WOE ID.

Implements flickr.places.getInfo (1.7)

Announced 2008-10-30 http://code.flickr.com/blog/2008/10/30/the-shape-of-alpha/ and in detail 2008-11-05 http://tech.groups.yahoo.com/group/yws-flickr/message/4510

`deprecated` : Replaced by `flickcurl_places_getInfo2()` with integer woe_id argument.

#### Parameters

fc | flickcurl context |
place_id | A Places ID (or NULL) |
woe_id | A Where On Earth (WOE) ID. (or NULL) |

#### Returns

new place object or NULL on failure

### flickcurl_places_getInfo2 ()

    flickcurl_place *
    flickcurl_places_getInfo2 (flickcurl *fc,
                               const char *place_id,
                               const int woe_id);

Get information about a place.

While optional, you must pass either a valid Places ID or a WOE ID.

Replaces `flickcurl_places_getInfo()` with integer woe_id argument.

#### Parameters

fc | flickcurl context |
place_id | A Places ID. (or NULL) |
woe_id | A Where On Earth (WOE) ID (or <0) |

#### Returns

new place object or NULL on failure

### flickcurl_places_getInfoByUrl ()

    flickcurl_place *
    flickcurl_places_getInfoByUrl (flickcurl *fc,
                                   const char *url);

Lookup information about a place, by its flickr.com/places URL.

Implements flickr.places.getInfoByUrl (1.7)

Announced 2008-10-30 http://code.flickr.com/blog/2008/10/30/the-shape-of-alpha/ and in detail 2008-11-05 http://tech.groups.yahoo.com/group/yws-flickr/message/4510

#### Parameters

fc | flickcurl context |
url | A flickr.com/places URL in the form of /country/region/city. For example: /Canada/Quebec/Montreal |

#### Returns

new place object or NULL on failure

### flickcurl_places_getPlaceTypes ()

    flickcurl_place_type_info **
    flickcurl_places_getPlaceTypes (flickcurl *fc);

Get a list of available place types

Implements flickr.places.getPlaceTypes (1.8)

#### Parameters

fc | flickcurl context |

#### Returns

array of flickcurl_place_type_info or NULL on failure

### flickcurl_places_getShapeHistory ()

    flickcurl_shapedata **
    flickcurl_places_getShapeHistory (flickcurl *fc,
                                      const char *place_id,
                                      int woe_id);

Return an historical list of all the shape data generated for a Places or Where on Earth (WOE) ID.

While optional, you must pass either a valid Places ID or a WOE ID.

Implements flickr.places.getShapeHistory (1.8)

Announced 2009-01-12 in http://tech.groups.yahoo.com/group/yws-flickr/message/4669

Addition of donut holes announced 2009-05-06 http://code.flickr.com/blog/2009/05/06/the-absence-and-the-anchor/

#### Parameters

fc | flickcurl context |
place_id | A Flickr Places ID (or NULL) |
woe_id | A Where On Earth (WOE) ID (or <0) |

#### Returns

NULL on failure

### flickcurl_places_getTopPlacesList ()

    flickcurl_place **
    flickcurl_places_getTopPlacesList (flickcurl *fc,
                                       flickcurl_place_type place_type,
                                       const char *date,
                                       int woe_id,
                                       const char *place_id);

Return the top 100 most geotagged places for a day.

Implements flickr.places.getTopPlacesList (1.12)

#### Parameters

fc | flickcurl context |
place_type | The place type to cluster photos by. Valid place types are : neighbourhood, locality, region, country and continent |
date | A valid date in YYYY-MM-DD format. The default is yesterday. (or NULL) |
woe_id | Limit your query to only those top places belonging to a specific Where on Earth (WOE) identifier. (or NULL) |
place_id | Limit your query to only those top places belonging to a specific Flickr Places identifier. (or NULL) |

#### Returns

array of places or NULL on failure

### flickcurl_place_id_to_type ()

    flickcurl_place_type
    flickcurl_place_id_to_type (int place_type_id);

Turn a place type into a place ID

#### Parameters

place_type_id | place type ID |

#### Returns

place type for fID or FLICKCURL_PLACE_LOCATION on failure

### flickcurl_places_placesForBoundingBox ()

    flickcurl_place **
    flickcurl_places_placesForBoundingBox (flickcurl *fc,
                                           flickcurl_place_type place_type,
                                           double minimum_longitude,
                                           double minimum_latitude,
                                           double maximum_longitude,
                                           double maximum_latitude);

Return all the locations of a matching place type for a bounding box.

The maximum allowable size of a bounding box (the distance between the SW and NE corners) is governed by the place type you are requesting. Allowable sizes are as follows: neighbourhood: 3km (1.8mi), locality: 7km (4.3mi), county: 50km (31mi), region: 200km (124mi), country: 500km (310mi), continent: 1500km (932mi)

Implements flickr.places.placesForBoundingBox (1.8)

#### Parameters

fc | flickcurl context |
place_type | The place type to cluster photos by |
minimum_longitude | Bound Box bottom-left corner longitude |
minimum_latitude | Bound Box bottom-left corner latitude |
maximum_longitude | Bound Box top-right corner longitude |
maximum_latitude | Bound Box top-right corner latitude |

#### Returns

non-0 on failure

### flickcurl_places_placesForContacts ()

    flickcurl_place **
    flickcurl_places_placesForContacts (flickcurl *fc,
                                        flickcurl_place_type place_type,
                                        int woe_id,
                                        const char *place_id,
                                        int threshold,
                                        const char *contacts,
                                        int min_upload_date,
                                        int max_upload_date,
                                        int min_taken_date,
                                        int max_taken_date);

Return a list of the top 100 unique places clustered by a given placetype for a user's contacts.

One of `woe_id` or `place_id` must be given.

Implements flickr.places.placesForContacts (1.8)

#### Parameters

fc | flickcurl context |
place_type | A specific place type to cluster photos by. |
woe_id | A Where on Earth ID to use to filter photo clusters (or NULL) |
place_id | A Places ID to use to filter photo clusters (or NULL) |
threshold | The minimum number of photos that a place type must have to be included. If the number of photos is lowered then the parent place type for that place will be used. |
contacts | Search your contacts. Either 'all' or 'ff' for just friends and family. (Default is 'all') (or NULL) |
min_upload_date | Minimum upload date. Photos with an upload date greater than or equal to this value will be returned (or <0) |
max_upload_date | Maximum upload date. Photos with an upload date less than or equal to this value will be returned (or <0) |
min_taken_date | Minimum taken date. Photos with an taken date greater than or equal to this value will be returned (or <0) |
max_taken_date | Maximum taken date. Photos with an taken date less than or equal to this value will be returned (or <0) |

#### Returns

non-0 on failure

### flickcurl_places_placesForUser ()

    flickcurl_place **
    flickcurl_places_placesForUser (flickcurl *fc,
                                    flickcurl_place_type place_type,
                                    int woe_id,
                                    const char *place_id,
                                    int threshold);

Return a list of the top 100 unique places clustered by a given place type for a user.

This API added 2008-09-04 as announced in http://code.flickr.com/blog/2008/09/04/whos-on-first/

Implements flickr.places.placesForUser (1.6)

#### Parameters

fc | flickcurl context |
place_type | A specific place type to cluster photos by. Valid places types are neighbourhood, locality, region or country |
woe_id | A Where on Earth ID to use to filter photo clusters. (or <0) |
place_id | A Places ID to use to filter photo clusters. (or NULL) |
threshold | The minimum number of photos that a place type must have to be included. If the number of photos is lowered then the parent place type for that place will be used. (or <0) |

#### Returns

non-0 on failure

### flickcurl_places_placesForTags ()

    int
    flickcurl_places_placesForTags (flickcurl *fc,
                                    flickcurl_place_type place_type,
                                    int woe_id,
                                    const char *place_id,
                                    const char *threshold,
                                    const char *tags,
                                    const char *tag_mode,
                                    const char *machine_tags,
                                    const char *machine_tag_mode,
                                    const char *min_upload_date,
                                    const char *max_upload_date,
                                    const char *min_taken_date,
                                    const char *max_taken_date);

Return a list of the top 100 unique places clustered by a given placetype for set of tags or machine tags.

Machine tags extra information. Aside from passing in a fully formed machine tag, there is a special syntax for searching on specific properties :

- Find photos using the 'dc' namespace : `"machine_tags" => "dc:"`
- Find photos with a title in the 'dc' namespace : `"machine_tags" => "dc:title = "`
- Find photos titled "mr. camera" in the 'dc' namespace : `"machine_tags" => "dc:title = \"mr. camera\"`
- Find photos whose value is "mr. camera" : `"machine_tags" => "*:* = \"mr. camera\""`
- Find photos that have a title, in any namespace : `"machine_tags" => "*:title = "`
- Find photos that have a title, in any namespace, whose value is "mr. camera" : `"machine_tags" => "*:title = \"mr. camera\""`
- Find photos, in the 'dc' namespace whose value is "mr. camera" : `"machine_tags" => "dc:* = \"mr. camera\""`

Implements flickr.places.placesForTags (1.8)

#### Parameters

fc | flickcurl context |
place_type | The place type to cluster photos by |
woe_id | A Where on Earth ID to use to filter photo clusters (or NULL) |
place_id | A Places ID to use to filter photo clusters (or NULL) |
threshold | The minimum number of photos that a place type must have to be included. If the number of photos is lowered then the parent place type for that place will be used. |
tags | A comma-delimited list of tags. Photos with one or more of the tags listed will be returned. (or NULL) |
tag_mode | Either 'any' for an OR combination of tags, or 'all' for an AND combination. Defaults to 'any' if not specified. (or NULL) |
machine_tags | Multiple machine tags may be queried by passing a comma-separated list. The number of machine tags you can pass in a single query depends on the tag mode (AND or OR) that you are querying with. "AND" queries are limited to (16) machine tags. "OR" queries are limited to (8). See below. (or NULL) |
machine_tag_mode | Either 'any' for an OR combination of tags, or 'all' for an AND combination. Defaults to 'any' if not specified. (or NULL) |
min_upload_date | Minimum upload date. Photos with an upload date greater than or equal to this value will be returned (or NULL) |
max_upload_date | Maximum upload date. Photos with an upload date less than or equal to this value will be returned (or NULL) |
min_taken_date | Minimum taken date. Photos with an taken date greater than or equal to this value will be returned (or NULL) |
max_taken_date | Maximum taken date. Photos with an taken date less than or equal to this value will be returned (or NULL) |

#### Returns

non-0 on failure

### flickcurl_places_resolvePlaceId ()

    flickcurl_place *
    flickcurl_places_resolvePlaceId (flickcurl *fc,
                                     const char *place_id);

Find places information by Place ID

Implements flickr.places.resolvePlaceId (1.0)

#### Parameters

fc | flickcurl context |
place_id | A Places ID |

#### Returns

new place object or NULL on failure

### flickcurl_places_resolvePlaceURL ()

    flickcurl_place *
    flickcurl_places_resolvePlaceURL (flickcurl *fc,
                                      const char *url);

Find Places information by Place URL

Implements flickr.places.resolvePlaceURL (1.0)

#### Parameters

fc | flickcurl context |
url | A Places URL. Place URLs are of the form /country/region/city |

#### Returns

non-0 on failure

### flickcurl_places_tagsForPlace ()

    flickcurl_tag **
    flickcurl_places_tagsForPlace (flickcurl *fc,
                                   int woe_id,
                                   const char *place_id,
                                   int min_upload_date,
                                   int max_upload_date,
                                   int min_taken_date,
                                   int max_taken_date);

Return a list of the top 100 unique tags for a Flickr Places or Where on Earth (WOE) ID

(While optional, you must pass either a valid Places ID or a WOE ID.)

Implements flickr.places.tagsForPlace (1.8)

#### Parameters

fc | flickcurl context |
woe_id | A Where on Earth identifier to use to filter photo clusters (or <0) |
place_id | A Flickr Places identifier to use to filter photo clusters (or NULL) |
min_upload_date | Minimum upload date. Photos with an upload date greater than or equal to this value will be returned. The date should be in the form of a unix timestamp. (or NULL) |
max_upload_date | Maximum upload date. Photos with an upload date less than or equal to this value will be returned. The date should be in the form of a unix timestamp. (or NULL) |
min_taken_date | Minimum taken date. Photos with an taken date greater than or equal to this value will be returned. The date should be in the form of a mysql datetime. (or NULL) |
max_taken_date | Maximum taken date. Photos with an taken date less than or equal to this value will be returned. The date should be in the form of a mysql datetime. (or NULL) |

#### Returns

NULL on failure

## Types and Values

### flickcurl_place

    typedef struct {
      char* names[FLICKCURL_PLACE_LAST+1];
      char* ids[FLICKCURL_PLACE_LAST+1];
      char* urls[FLICKCURL_PLACE_LAST+1];
      flickcurl_place_type type;
      char* woe_ids[FLICKCURL_PLACE_LAST+1];
      flickcurl_location location;
      int count;

      /* DEPRECATED shapefile fields; now are pointers into @shape */
      char* shapedata;
      size_t shapedata_length;
      char** shapefile_urls;
      int shapefile_urls_count;

      struct flickcurl_shapedata_s* shape;
      char* timezone;
    } flickcurl_place;

A Place.

Index 0 in the array is the location itself. `flickcurl_get_place_type_label()` can give labels for the array indexes of type flickcurl_place_type.

#### Members

char *`names`[FLICKCURL_PLACE_LAST+1]; | Array of place names |
char *`ids`[FLICKCURL_PLACE_LAST+1]; | Array of place IDs |
char *`urls`[FLICKCURL_PLACE_LAST+1]; | Array of place urls. |
flickcurl_place_type `type`; | Location type of index 0 (the location) usually FLICKCURL_PLACE_LOCATION but may be wider |
char *`woe_ids`[FLICKCURL_PLACE_LAST+1]; | Array of WOE IDs |
flickcurl_location `location`; | location for this place |
int `count`; | count of photos (when used for `flickcurl_places_placesForUser()` ) |
char *`shapedata`; | DEPRECATED for `shape->data` : XML string of <shapedata> element and content elements when present (or NULL) |
size_t `shapedata_length`; | DEPRECATED for `shape->data_length` : size of `shapedate` string |
char **`shapefile_urls`; | DEPRECATED for `shape->file_urls` : NULL-terminated array of pointers to shapefile URLs when present (or NULL) |
int `shapefile_urls_count`; | DEPRECATED for `shape->file_urls_count` : number of entries in `shapefile_urls` array |
struct flickcurl_shapedata_s *`shape`; | shapefile data (inline data and shapefile urls) |
char *`timezone`; | timezone of location in 'zoneinfo' format such as âEurope/Parisâ. |

### enum flickcurl_place_type

Place type

#### Members

FLICKCURL_PLACE_LOCATION | a general location |
FLICKCURL_PLACE_NEIGHBOURHOOD | neighborhood (narrowest place) |
FLICKCURL_PLACE_NEIGHBORHOOD | deprecated |
FLICKCURL_PLACE_LOCALITY | locality |
FLICKCURL_PLACE_COUNTY | county |
FLICKCURL_PLACE_REGION | region |
FLICKCURL_PLACE_COUNTRY | country |
FLICKCURL_PLACE_CONTINENT | continent (widest place) (Flickcurl 1.8) |
FLICKCURL_PLACE_LAST | internal offset to last in enum list |

### flickcurl_place_type_info

    typedef struct {
      flickcurl_place_type type;
      int id;
      char *name;
    } flickcurl_place_type_info;

Place type information

#### Members

flickcurl_place_type `type`; | type enum ID |
int `id`; | web service call ID |
char *`name`; | name |