## Tags

Tags — Photo tagging.

## Synopsis

                        flickcurl_tag;
                        flickcurl_tag_cluster;
                        flickcurl_tag_clusters;
    void                flickcurl_free_tag                  (flickcurl_tag *t);
    void                flickcurl_free_tags                 (flickcurl_tag **tags);
    void                flickcurl_free_tag_clusters         (flickcurl_tag_clusters *tcs);
    void                (*flickcurl_tag_handler)            (void *user_data,
                                                             flickcurl_tag *tag);
    flickcurl_photos_list * flickcurl_tags_getClusterPhotos (flickcurl *fc,
                                                             const char *tag,
                                                             const char *cluster_id,
                                                             flickcurl_photos_list_params *list_params);
    flickcurl_tag_clusters * flickcurl_tags_getClusters     (flickcurl *fc,
                                                             const char *tag);
    flickcurl_tag **    flickcurl_tags_getHotList           (flickcurl *fc,
                                                             const char *period,
                                                             int tag_count);
    flickcurl_tag **    flickcurl_tags_getListPhoto         (flickcurl *fc,
                                                             const char *photo_id);
    flickcurl_tag **    flickcurl_tags_getListUser          (flickcurl *fc,
                                                             const char *user_id);
    flickcurl_tag **    flickcurl_tags_getListUserPopular   (flickcurl *fc,
                                                             const char *user_id,
                                                             int pop_count);
    flickcurl_tag **    flickcurl_tags_getListUserRaw       (flickcurl *fc,
                                                             const char *tag);
    flickcurl_tag **    flickcurl_tags_getMostFrequentlyUsed
                                                            (flickcurl *fc);
    flickcurl_tag **    flickcurl_tags_getRelated           (flickcurl *fc,
                                                             const char *tag);

## Description

Photo tagging.

## Details

### flickcurl_tag

    typedef struct {
      struct flickcurl_photo_s* photo;
      char* id;
      char* author;
      char* authorname;
      char* raw;
      char* cooked;
      int machine_tag;
      int count;
    } flickcurl_tag;

A tag OR a posting of a tag about a photo by a user OR a tag in a histogram

Most of these fields may be NULL, 0 for numbers but not all. Either `raw` or `cooked` MUST appear.

A Photo Tag.

struct flickcurl_photo_s *`photo`; | Associated photo object if any
char *`id`; | tag identifier
char *`author`; | author (may be NULL)
char *`authorname`; | author real name (may be NULL)
char *`raw`; | raw tag as user typed it (may be NULL, but if so `cooked` must be not NULL)
char *`cooked`; | cooked tag (may be NULL, but if so `raw` must not be NULL)
int `machine_tag`; | boolean (non-0 true) if tag is a Machine Tag
int `count`; | tag count in a histogram (or 0)

### flickcurl_tag_cluster

    typedef struct {
      int count;
      char** tags;
    } flickcurl_tag_cluster;

A cluster (set) of tag names

int `count`; | number of tags
char **`tags`; | tags in this cluster

### flickcurl_tag_clusters

    typedef struct {
      int count;
      flickcurl_tag_cluster** clusters;
    } flickcurl_tag_clusters;

A set of clusters of tag names

int `count`; | number of tag clusters
flickcurl_tag_cluster **`clusters`; | tag clusters

### flickcurl_free_tag ()

    void                flickcurl_free_tag                  (flickcurl_tag *t);

Destructor for tag object

`t` : | tag object

### flickcurl_free_tags ()

    void                flickcurl_free_tags                 (flickcurl_tag **tags);

Destructor for array of tag objects

`tags` : | tag object array

### flickcurl_free_tag_clusters ()

    void                flickcurl_free_tag_clusters         (flickcurl_tag_clusters *tcs);

Destructor for tag clusters object

`tcs` : | tag clusters object

### flickcurl_tag_handler ()

    void                (*flickcurl_tag_handler)            (void *user_data,
                                                             flickcurl_tag *tag);

Flickcurl Tag handler callback.

`user_data` : | user data pointer
`tag` : | tag

### flickcurl_tags_getClusterPhotos ()

    flickcurl_photos_list * flickcurl_tags_getClusterPhotos (flickcurl *fc,
                                                             const char *tag,
                                                             const char *cluster_id,
                                                             flickcurl_photos_list_params *list_params);

Returns the first 24 photos for a given tag cluster

Implements flickr.tags.getClusterPhotos (1.7)

Added to API (not announced) some time between 2008-09-04 and 2008-09-19

`fc` : | flickcurl context
`tag` : | The tag that this cluster belongs to.
`cluster_id` : | The top three tags for the cluster, separated by dashes (just like the url).
`list_params` : | flickcurl_photos_list_params result parameters (or NULL)
Returns : | non-0 on failure

### flickcurl_tags_getClusters ()

    flickcurl_tag_clusters * flickcurl_tags_getClusters     (flickcurl *fc,
                                                             const char *tag);

Gives you a list of tag clusters for the given tag.

Implements flickr.tags.getClusters (1.5)

"There is no pagination for this method as the number of clusters for a single tag is capped at 5 and each cluster may contain between 1 - 50 tags (give or take)."

As announced 2008-07-17 http://tech.groups.yahoo.com/group/yws-flickr/message/4218

`fc` : | flickcurl context
`tag` : | The tag to fetch clusters for.
Returns : | NULL on failure

### flickcurl_tags_getHotList ()

    flickcurl_tag **    flickcurl_tags_getHotList           (flickcurl *fc,
                                                             const char *period,
                                                             int tag_count);

Returns a list of hot tags for the given period.

Implements flickr.tags.getHotList (0.9)

`fc` : | flickcurl context
`period` : | The period for which to fetch hot tags. Valid values are day and week (defaults to day).
`tag_count` : | The number of tags to return. Defaults to 20. Maximum allowed value is 200 (or -1 to leave as default)
Returns : | array of flickcurl_tag or NULL on failure

### flickcurl_tags_getListPhoto ()

    flickcurl_tag **    flickcurl_tags_getListPhoto         (flickcurl *fc,
                                                             const char *photo_id);

Get the tag list for a given photo.

Implements flickr.tags.getListPhoto (0.9)

`fc` : | flickcurl context
`photo_id` : | photo ID
Returns : | array of flickcurl_tag or NULL on failure

### flickcurl_tags_getListUser ()

    flickcurl_tag **    flickcurl_tags_getListUser          (flickcurl *fc,
                                                             const char *user_id);

Get the tag list for a given user (or current user)

Implements flickr.tags.getListUser (0.9)

FIXME: API docs says user_id is optional but it is not.

`fc` : | flickcurl context
`user_id` : | user NSID (or NULL)
Returns : | array of flickcurl_tag or NULL on failure

### flickcurl_tags_getListUserPopular ()

    flickcurl_tag **    flickcurl_tags_getListUserPopular   (flickcurl *fc,
                                                             const char *user_id,
                                                             int pop_count);

Get the popular tag list for a given user (or current user)

Implements flickr.tags.getListUserPopular (0.9)

`fc` : | flickcurl context
`user_id` : | user NSID (or NULL)
`pop_count` : | number of popular tags to return (or <0 for default)
Returns : | array of flickcurl_tag or NULL on failure

### flickcurl_tags_getListUserRaw ()

    flickcurl_tag **    flickcurl_tags_getListUserRaw       (flickcurl *fc,
                                                             const char *tag);

Get the raw versions of a given tag (or all tags) for the currently logged-in user.

Implements flickr.tags.getListUserRaw (0.9)

`fc` : | flickcurl context
`tag` : | tag to get raw version of (or NULL for all)
Returns : | array of flickcurl_tag or NULL on failure

### flickcurl_tags_getMostFrequentlyUsed ()

    flickcurl_tag **    flickcurl_tags_getMostFrequentlyUsed
                                                            (flickcurl *fc);

Returns a list of most frequently used tags for a user.

Implements flickr.tags.getMostFrequentlyUsed (1.25)

`fc` : | flickcurl context
Returns : | array of flickcurl_tag or NULL on failure

### flickcurl_tags_getRelated ()

    flickcurl_tag **    flickcurl_tags_getRelated           (flickcurl *fc,
                                                             const char *tag);

Get a list of tags 'related' to the given tag, based on clustered usage analysis.

Implements flickr.tags.getRelated (0.9)

`fc` : | flickcurl context
`tag` : | tag to fetch related tags for
Returns : | array of flickcurl_tag or NULL on failure