                    Flickcurl: C library for the Flickr API

Dave Beckett

   Flickcurl is a C library for the Flickr API, handling creating the
   requests, signing, token management, calling the API, marshalling
   request parameters and decoding responses. It uses libcurl to call the
   REST web service and libxml2 to manipulate the XML responses. Flickcurl
   supports all of the API (see Flickcurl API coverage for details)
   including the functions for photo/video uploading, browsing, searching,
   adding and editing comments, groups, notes, photosets, categories,
   activity, blogs, favorites, places, tags, machine tags, institutions,
   pandas and photo/video metadata. It also includes a program flickrdf to
   turn photo metadata, tags, machine tags and places into an RDF triples
   description.

   License: LGPL 2.1+ / GPL 2+ / Apache 2.0+

   Download: http://download.dajobe.org/flickcurl/

   Docs: Flickcurl API reference manual

   News: Flickcurl News including changes

   Requirements: the following libraries are needed:
     * libcurl 7.10.0 or newer
     * libxml2 2.6.8 or newer
     * raptor 2.0.0 (optional)

   Then do the usual ./configure, make and make install sequence to
   install the library and the flickcurl and flickrdf utilities.

   GitHub hosts the sources for Flickcurl at the GitHub flickcurl project
   page.

   Checkout with:
  git clone git://github.com/dajobe/flickcurl.git

  # Get the libmtwist submodule and fetch its content with:

  git submodule update --init

Flickr API Configuration

   The library needs to know your Flickr API OAuth token, token secret,
   client key and client secret, suitable for calling some of the API
   calls. To obtain these, you need to apply for API keys at the Flickr
   Services site. When using the utility programs, this information should
   be stored in the ~/.flickcurl.conf file so that it can be read at
   run-time. The configuration file has the format:
[flickr]
oauth_token=12345678901234567-abcdef0123456789
oauth_token_secret=abcdef9876543210
oauth_client_key=0123456789abcdef0123456789abcdef
oauth_client_secret=fedcba9876543210

   See Authenticating Flickcurl for OAuth in the manual for full details
   of how to build flickcurl, authenticate and set up the configuration
   file above.

Utility programs

  flickcurl - call Flickr API

   This can call some of the Flickr APIs plus help with OAuth
   authentication steps to get the final set of tokens and secrets and
   writing them into ~/.flickcurl.conf file. Use flickcurl -h to get a
   list of the supported commands and their arguments.

   This example calls the photos.getInfo API via the photos-getInfo
   command on photo 196308964 which decodes the returned XML into fields
   in a flickcurl_photo structure which are then printed with their
   datatype, string value and integer value (or -1 if it has none). All
   dateTime values are converted into both the ISO format string (such as
   used by Web and XML standards) and unix time integers. Photo tags are
   also returned when present along with their id, author, raw, cooked and
   machine tag status.
$ flickcurl photos.getInfo 196308964
flickcurl: photo with URI http://www.flickr.com/photos/dajobe/196308964/ ID 1963
08964 and 5 tags
    field dateuploaded (1) with dateTime value: '2006-07-23T18:16:13Z' / 1153678
573
    field farm (2) with integer value: '1' / 1
    field isfavorite (3) with boolean value: '0' / 0
    field license (4) with integer value: '1' / 1
    field originalformat (5) with string value: 'jpg' / -1
    field rotation (6) with integer value: '0' / 0
    field server (7) with integer value: '57' / 57
    field dates_lastupdate (8) with dateTime value: '2007-02-25T07:45:46Z' / 117
2389546
    field dates_posted (9) with dateTime value: '2006-07-23T18:16:13Z' / 1153678
573
    field dates_taken (10) with string value: '2006-07-22 22:28:50' / -1
    field dates_takengranularity (11) with integer value: '0' / 0
    field editability_canaddmeta (13) with boolean value: '1' / 1
    field editability_cancomment (14) with boolean value: '1' / 1
    field geoperms_iscontact (15) with boolean value: '0' / 0
    field geoperms_isfamily (16) with boolean value: '0' / 0
    field geoperms_isfriend (17) with boolean value: '0' / 0
    field geoperms_ispublic (18) with boolean value: '1' / 1
    field location_accuracy (19) with integer value: '12' / 12
    field location_latitude (20) with float value: '36.620487' / -1
    field location_longitude (21) with float value: '-121.904468' / -1
    field owner_location (22) with string value: 'Mountain View, California, USA
' / -1
    field owner_nsid (23) with string value: '13355580@N00' / -1
    field owner_realname (24) with string value: 'Dave Beckett' / -1
    field owner_username (25) with string value: 'dajobe' / -1
    field title (26) with string value: 'Jellyfish at Monterey Aquarium' / -1
    field visibility_isfamily (27) with boolean value: '0' / 0
    field visibility_isfriend (28) with boolean value: '0' / 0
    field visibility_ispublic (29) with boolean value: '1' / 1
    field secret (30) with string value: 'b34cb0af68' / -1
    field originalsecret (31) with string value: 'b34cb0af68' / -1
    field location_locality (33) with string value: 'Pacific Grove' / -1
    field location_region (35) with string value: 'California' / -1
    field location_country (36) with string value: 'United States' / -1
    field location_placeid (37) with string value: 'J1HdelRTVrx7R.g2' / -1
    field locality_placeid (39) with string value: 'J1HdelRTVrx7R.g2' / -1
    field county_placeid (40) with string value: 'fpIAzjpQUL9F5MEpDw' / -1
    field region_placeid (41) with string value: 'NsbUWfBTUb4mbyVu' / -1
    field country_placeid (42) with string value: 'nz.gsghTUb4c2WAecA' / -1
    field location_woeid (43) with string value: '2467327' / -1
    field locality_woeid (45) with string value: '2467327' / -1
    field county_woeid (46) with string value: '12587696' / -1
    field region_woeid (47) with string value: '2347563' / -1
    field country_woeid (48) with string value: '23424977' / -1
    field usage_candownload (49) with boolean value: '1' / 1
    field usage_canblog (50) with boolean value: '1' / 1
    field usage_canprint (51) with boolean value: '1' / 1
    field views (56) with integer value: '529' / 529
tags:
0) regular tag: id 94493-196308964-3362 author ID 13355580@N00 name (Unknown) ra
w 'jellyfish' cooked 'jellyfish' count 0
1) regular tag: id 94493-196308964-119180 author ID 13355580@N00 name (Unknown)
raw 'montereyaquarium' cooked 'montereyaquarium' count 0
2) regular tag: id 94493-196308964-2443 author ID 13355580@N00 name (Unknown) ra
w 'monterey' cooked 'monterey' count 0
3) machine tag: id 94493-196308964-8499312 author ID 13355580@N00 name (Unknown)
 raw 'xmlns:dc=http://purl.org/dc/elements/1.1/' cooked 'xmlns:dc=httppurlorgdce
lements11' count 0
4) machine tag: id 94493-196308964-8499315 author ID 13355580@N00 name (Unknown)
 raw 'dc:subject=jellyfish' cooked 'dc:subject=jellyfish' count 0
notes:
  Location: latitude 36.620487  longitude -121.904468  accuracy unknown
  0) place location: name '
                ' id J1HdelRTVrx7R.g2 woeid 2467327
  2) place locality: name 'Pacific Grove' id J1HdelRTVrx7R.g2 woeid 2467327
  3) place county: name 'Monterey' id fpIAzjpQUL9F5MEpDw woeid 12587696
  4) place region: name 'California' id NsbUWfBTUb4mbyVu woeid 2347563
  5) place country: name 'United States' id nz.gsghTUb4c2WAecA woeid 23424977

  flickrdf - generate RDF triples from a Flickr photo

   This utility uses the photos.getInfo API to interpret the description
   fields, tags and places for a photo URI into RDF triples. If raptor is
   present, it will be used to provide proper serializing to RDF rather
   than the built in and hacky ntriples/turtle output.

   Machine tags when they are found are scanned for xmlns:prefix=uri and
   then all other machine tags with that prefix turn into triples. Several
   prefixes are also pre-defined by the library to automatically get
   turned into triples without an xmlns, such as blue:, cell:, filter: and
   geo:. Non-machine tags are not yet interpreted.

   Places attached to photos are turned into extra information blocks
   (sets of triples) hung off a places:place predicate.
<http://www.flickr.com/photos/dajobe/196308964/> <http://purl.org/dc/terms/creat
or> _:person .
_:person <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foa
f/0.1/#Person> .
_:person <http://xmlns.com/foaf/0.1/#maker> <http://www.flickr.com/photos/dajobe
/196308964/> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://purl.org/dc/terms/dateS
ubmitted> "2006-07-23T18:16:13Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://purl.org/dc/terms/right
s> <http://creativecommons.org/licenses/by-nc-sa/2.0/> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://purl.org/dc/terms/modif
ied> "2007-02-25T07:45:46Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://purl.org/dc/terms/issue
d> "2006-07-23T18:16:13Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://purl.org/dc/terms/creat
ed> "2006-07-22T22:28:50Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://www.w3.org/2003/01/geo/
wgs84_pos#lat> "36.620487"^^<http://www.w3.org/2001/XMLSchema#double> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://www.w3.org/2003/01/geo/
wgs84_pos#long> "-121.904468"^^<http://www.w3.org/2001/XMLSchema#double> .
_:person <http://xmlns.com/foaf/0.1/#name> "Dave Beckett" .
_:person <http://xmlns.com/foaf/0.1/#nick> "dajobe" .
<http://www.flickr.com/photos/dajobe/196308964/> <http://purl.org/dc/terms/title
> "Jellyfish at Monterey Aquarium" .
<http://www.flickr.com/photos/dajobe/196308964/> <http://purl.org/dc/elements/1.
1/subject> "jellyfish" .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Plac
es#place> _:place0 .
_:place0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://machinetags.o
rg/ns/Places#Place> .
_:place0 <http://machinetags.org/ns/Places#type> "location" .
_:place0 <http://machinetags.org/ns/Places#id> "WM3JEXSbBZqqRtGA" .
_:place0 <http://machinetags.org/ns/Places#placeid> "2467327" .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Plac
es#place> _:place2 .
_:place2 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://machinetags.o
rg/ns/Places#Place> .
_:place2 <http://machinetags.org/ns/Places#type> "locality" .
_:place2 <http://machinetags.org/ns/Places#name> "Pacific Grove" .
_:place2 <http://machinetags.org/ns/Places#id> "WM3JEXSbBZqqRtGA" .
_:place2 <http://machinetags.org/ns/Places#placeid> "2467327" .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Plac
es#place> _:place3 .
_:place3 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://machinetags.o
rg/ns/Places#Place> .
_:place3 <http://machinetags.org/ns/Places#type> "county" .
_:place3 <http://machinetags.org/ns/Places#name> "Monterey" .
_:place3 <http://machinetags.org/ns/Places#id> "AQ4UpRqYA5l0BiyF.A" .
_:place3 <http://machinetags.org/ns/Places#placeid> "12587696" .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Plac
es#place> _:place4 .
_:place4 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://machinetags.o
rg/ns/Places#Place> .
_:place4 <http://machinetags.org/ns/Places#type> "region" .
_:place4 <http://machinetags.org/ns/Places#name> "California" .
_:place4 <http://machinetags.org/ns/Places#id> "SVrAMtCbAphCLAtP" .
_:place4 <http://machinetags.org/ns/Places#placeid> "2347563" .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Plac
es#place> _:place5 .
_:place5 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://machinetags.o
rg/ns/Places#Place> .
_:place5 <http://machinetags.org/ns/Places#type> "country" .
_:place5 <http://machinetags.org/ns/Places#name> "United States" .
_:place5 <http://machinetags.org/ns/Places#id> "4KO02SibApitvSBieQ" .
_:place5 <http://machinetags.org/ns/Places#placeid> "23424977" .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Flic
kr#photo> <http://farm1.static.flickr.com/57/196308964_b34cb0af68_s.jpg> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_s.jpg> <http://www.w3.or
g/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/#Image> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_s.jpg> <http://www.w3.or
g/2000/01/rdf-schema#label> "Square" .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_s.jpg> <http://machineta
gs.org/ns/Flickr#width> "75"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_s.jpg> <http://machineta
gs.org/ns/Flickr#height> "75"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Flic
kr#photo> <http://farm1.static.flickr.com/57/196308964_b34cb0af68_t.jpg> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_t.jpg> <http://www.w3.or
g/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/#Image> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_t.jpg> <http://www.w3.or
g/2000/01/rdf-schema#label> "Thumbnail" .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_t.jpg> <http://machineta
gs.org/ns/Flickr#width> "75"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_t.jpg> <http://machineta
gs.org/ns/Flickr#height> "100"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Flic
kr#photo> <http://farm1.static.flickr.com/57/196308964_b34cb0af68_m.jpg> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_m.jpg> <http://www.w3.or
g/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/#Image> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_m.jpg> <http://www.w3.or
g/2000/01/rdf-schema#label> "Small" .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_m.jpg> <http://machineta
gs.org/ns/Flickr#width> "180"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_m.jpg> <http://machineta
gs.org/ns/Flickr#height> "240"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Flic
kr#photo> <http://farm1.static.flickr.com/57/196308964_b34cb0af68.jpg> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68.jpg> <http://www.w3.org/
1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/#Image> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68.jpg> <http://www.w3.org/
2000/01/rdf-schema#label> "Medium" .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68.jpg> <http://machinetags
.org/ns/Flickr#width> "375"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68.jpg> <http://machinetags
.org/ns/Flickr#height> "500"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://www.flickr.com/photos/dajobe/196308964/> <http://machinetags.org/ns/Flic
kr#photo> <http://farm1.static.flickr.com/57/196308964_b34cb0af68_o.jpg> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_o.jpg> <http://www.w3.or
g/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/#Image> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_o.jpg> <http://www.w3.or
g/2000/01/rdf-schema#label> "Original" .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_o.jpg> <http://machineta
gs.org/ns/Flickr#width> "600"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://farm1.static.flickr.com/57/196308964_b34cb0af68_o.jpg> <http://machineta
gs.org/ns/Flickr#height> "800"^^<http://www.w3.org/2001/XMLSchema#integer> .

   If you have raptor installed, you can get nicer RDF triples out and
   with rapper 1.4.14+, pretty-printed turtle:
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dc: <http://purl.org/dc/elements/1.1/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/#> .
@prefix geo: <http://www.w3.org/2003/01/geo/wgs84_pos#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix places: <http://machinetags.org/ns/Places#> .
@prefix flickr: <http://machinetags.org/ns/Flickr#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<http://www.flickr.com/photos/dajobe/196308964/>
    flickr:photo <http://farm1.static.flickr.com/57/196308964_b34cb0af68.jpg>, <
http://farm1.static.flickr.com/57/196308964_b34cb0af68_m.jpg>, <http://farm1.sta
tic.flickr.com/57/196308964_b34cb0af68_o.jpg>, <http://farm1.static.flickr.com/5
7/196308964_b34cb0af68_s.jpg>, <http://farm1.static.flickr.com/57/196308964_b34c
b0af68_t.jpg> ;
    places:place [
        places:id "WM3JEXSbBZqqRtGA" ;
        places:placeid "2467327" ;
        places:type "location" ;
        a places:Place
    ], [
        places:id "WM3JEXSbBZqqRtGA" ;
        places:name "Pacific Grove" ;
        places:placeid "2467327" ;
        places:type "locality" ;
        a places:Place
    ], [
        places:id "AQ4UpRqYA5l0BiyF.A" ;
        places:name "Monterey" ;
        places:placeid "12587696" ;
        places:type "county" ;
        a places:Place
    ], [
        places:id "SVrAMtCbAphCLAtP" ;
        places:name "California" ;
        places:placeid "2347563" ;
        places:type "region" ;
        a places:Place
    ], [
        places:id "4KO02SibApitvSBieQ" ;
        places:name "United States" ;
        places:placeid "23424977" ;
        places:type "country" ;
        a places:Place
    ] ;
    dc:subject "jellyfish" ;
    dcterms:created "2006-07-22T22:28:50Z"^^xsd:dateTime ;
    dcterms:creator [
        a foaf:Person ;
        foaf:maker <http://www.flickr.com/photos/dajobe/196308964/> ;
        foaf:name "Dave Beckett" ;
        foaf:nick "dajobe"
    ] ;
    dcterms:dateSubmitted "2006-07-23T18:16:13Z"^^xsd:dateTime ;
    dcterms:issued "2006-07-23T18:16:13Z"^^xsd:dateTime ;
    dcterms:modified "2007-02-25T07:45:46Z"^^xsd:dateTime ;
    dcterms:rights <http://creativecommons.org/licenses/by-nc-sa/2.0/> ;
    dcterms:title "Jellyfish at Monterey Aquarium" ;
    geo:lat 36.620487 ;
    geo:long -121.904468 .

<http://farm1.static.flickr.com/57/196308964_b34cb0af68_s.jpg>
    flickr:height 75 ;
    flickr:width 75 ;
    a foaf:Image ;
    rdfs:label "Square" .

<http://farm1.static.flickr.com/57/196308964_b34cb0af68_t.jpg>
    flickr:height 100 ;
    flickr:width 75 ;
    a foaf:Image ;
    rdfs:label "Thumbnail" .

<http://farm1.static.flickr.com/57/196308964_b34cb0af68_m.jpg>
    flickr:height 240 ;
    flickr:width 180 ;
    a foaf:Image ;
    rdfs:label "Small" .

<http://farm1.static.flickr.com/57/196308964_b34cb0af68.jpg>
    flickr:height 500 ;
    flickr:width 375 ;
    a foaf:Image ;
    rdfs:label "Medium" .

<http://farm1.static.flickr.com/57/196308964_b34cb0af68_o.jpg>
    flickr:height 800 ;
    flickr:width 600 ;
    a foaf:Image ;
    rdfs:label "Original" .

Library use example

   See examples/print-photo-info.c
#include <stdio.h>
#include <flickcurl.h>

int main(int argc, char *argv[]);

int main(int argc, char *argv[]) {
  flickcurl *fc;
  flickcurl_photo *photo;
  flickcurl_photo_field_type field_type;
  int i;

  flickcurl_init(); /* optional static initialising of resources */
  fc = flickcurl_new();

  /* Set configuration, or more likely read from a config file */
  flickcurl_set_oauth_client_key(fc, "...");
  flickcurl_set_oauth_client_secret(fc, "...");
  flickcurl_set_oauth_token(fc, "...");
  flickcurl_set_oauth_token_secret(fc, "...");

  photo = flickcurl_photos_getInfo(fc, "123456789"); /* photo ID */

  for(field_type = 0; field_type <= PHOTO_FIELD_LAST; field_type++) {
    flickcurl_field_value_type datatype = photo->fields[field_type].type;

    if(datatype != VALUE_TYPE_NONE)
      fprintf(stderr, "field %s (%d) with %s value: '%s' / %d\n",
              flickcurl_get_photo_field_label(field_type), (int)field_type,
              flickcurl_get_field_value_type_label(datatype),
              photo->fields[field_type].string,
              photo->fields[field_type].integer);
  }

  for(i = 0; i < photo->tags_count; i++) {
    flickcurl_tag* tag=photo->tags[i];
    fprintf(stderr,
            "%d) %s tag: id %s author ID %s name %s raw '%s' cooked '%s' count %
d\n",
            i, (tag->machine_tag ? "machine" : "regular"),
            tag->id, tag->author,
            (tag->authorname ? tag->authorname : "(Unknown)"),
            tag->raw, tag->cooked,
            tag->count);
  }

  flickcurl_free_photo(photo);
  flickcurl_free(fc);
  flickcurl_finish(); /* optional static free of resources */

  return 0;
}

   For more extensive example code, see the source of the flickcurl
   utility in flickcurl.c which has code that calls all the API functions.
     __________________________________________________________________

   Copyright (C) 2007-2014 Dave Beckett
