## section-tag

section-tag

## Functions

void | flickcurl_free_tag ()
void | flickcurl_free_tags ()
void | flickcurl_free_tag_clusters ()
void | (*flickcurl_tag_handler) ()
flickcurl_photos_list * | flickcurl_tags_getClusterPhotos ()
flickcurl_tag_clusters * | flickcurl_tags_getClusters ()
flickcurl_tag ** | flickcurl_tags_getHotList ()
flickcurl_tag ** | flickcurl_tags_getListPhoto ()
flickcurl_tag ** | flickcurl_tags_getListUser ()
flickcurl_tag ** | flickcurl_tags_getListUserPopular ()
flickcurl_tag ** | flickcurl_tags_getListUserRaw ()
flickcurl_tag ** | flickcurl_tags_getMostFrequentlyUsed ()
flickcurl_tag ** | flickcurl_tags_getRelated ()

## Types and Values

| flickcurl_tag
| flickcurl_tag_cluster
| flickcurl_tag_clusters

## Description

## Functions

### flickcurl_free_tag ()

    void
    flickcurl_free_tag (flickcurl_tag *t);

Destructor for tag object

#### Parameters

t | tag object |

### flickcurl_free_tags ()

    void
    flickcurl_free_tags (flickcurl_tag **tags);

Destructor for array of tag objects

#### Parameters

tags | tag object array |

### flickcurl_free_tag_clusters ()

    void
    flickcurl_free_tag_clusters (flickcurl_tag_clusters *tcs);

Destructor for tag clusters object

#### Parameters

tcs | tag clusters object |

### flickcurl_tag_handler ()

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

Flickcurl Tag handler callback.

#### Parameters

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

#### Parameters

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

#### Parameters

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)

#### Parameters

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)

#### Parameters

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.

#### Parameters

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)

#### Parameters

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)

#### Parameters

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)

#### Parameters

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)

#### Parameters

fc | flickcurl context |
tag | tag to fetch related tags for |

#### Returns

array of flickcurl_tag or NULL on failure

## Types and Values

### 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.

#### Members

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

#### Members

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

#### Members

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