Place

Place — Places in the real world.

Synopsis

                    flickcurl_place;
void                flickcurl_free_place                (flickcurl_place *place);
void                flickcurl_free_places               (flickcurl_place **places_object);
enum                flickcurl_place_type;
                    flickcurl_place_type_info;
int                 flickcurl_place_type_to_id          (flickcurl_place_type place_type);
void                flickcurl_free_place_type_infos     (flickcurl_place_type_info **ptis_object);
flickcurl_place_type flickcurl_get_place_type_by_label  (const char *place_label);
const char *        flickcurl_get_place_type_label      (flickcurl_place_type place_type);
flickcurl_place **  flickcurl_places_find               (flickcurl *fc,
                                                         const char *query);
flickcurl_place *   flickcurl_places_findByLatLon       (flickcurl *fc,
                                                         double lat,
                                                         double lon,
                                                         int accuracy);
flickcurl_place **  flickcurl_places_forUser            (flickcurl *fc,
                                                         flickcurl_place_type place_type,
                                                         int woe_id,
                                                         const char *place_id,
                                                         int threshold);
flickcurl_place **  flickcurl_places_getChildrenWithPhotosPublic
                                                        (flickcurl *fc,
                                                         const char *place_id,
                                                         const char *woe_id);
flickcurl_place **  flickcurl_places_getChildrenWithPhotosPublic2
                                                        (flickcurl *fc,
                                                         const char *place_id,
                                                         int woe_id);
flickcurl_place *   flickcurl_places_getInfo            (flickcurl *fc,
                                                         const char *place_id,
                                                         const char *woe_id);
flickcurl_place *   flickcurl_places_getInfo2           (flickcurl *fc,
                                                         const char *place_id,
                                                         const int woe_id);
flickcurl_place *   flickcurl_places_getInfoByUrl       (flickcurl *fc,
                                                         const char *url);
flickcurl_place_type_info ** flickcurl_places_getPlaceTypes
                                                        (flickcurl *fc);
flickcurl_shapedata ** flickcurl_places_getShapeHistory (flickcurl *fc,
                                                         const char *place_id,
                                                         int woe_id);
flickcurl_place **  flickcurl_places_getTopPlacesList   (flickcurl *fc,
                                                         flickcurl_place_type place_type,
                                                         const char *date,
                                                         int woe_id,
                                                         const char *place_id);
flickcurl_place_type flickcurl_place_id_to_type         (int place_type_id);
flickcurl_place **  flickcurl_places_placesForBoundingBox
                                                        (flickcurl *fc,
                                                         flickcurl_place_type place_type,
                                                         double minimum_longitude,
                                                         double minimum_latitude,
                                                         double maximum_longitude,
                                                         double maximum_latitude);
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);
flickcurl_place **  flickcurl_places_placesForUser      (flickcurl *fc,
                                                         flickcurl_place_type place_type,
                                                         int woe_id,
                                                         const char *place_id,
                                                         int threshold);
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);
flickcurl_place *   flickcurl_places_resolvePlaceId     (flickcurl *fc,
                                                         const char *place_id);
flickcurl_place *   flickcurl_places_resolvePlaceURL    (flickcurl *fc,
                                                         const char *url);
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);

Description

Places in the real world.

Details

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.

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

flickcurl_free_place ()

void                flickcurl_free_place                (flickcurl_place *place);

Destructor for place object

place :

place object

flickcurl_free_places ()

void                flickcurl_free_places               (flickcurl_place **places_object);

Destructor for array of place object

places_object :

place object array

enum flickcurl_place_type

typedef enum {
  FLICKCURL_PLACE_LOCATION,
  FLICKCURL_PLACE_NEIGHBOURHOOD,
  FLICKCURL_PLACE_NEIGHBORHOOD = FLICKCURL_PLACE_NEIGHBOURHOOD,
  FLICKCURL_PLACE_LOCALITY,
  FLICKCURL_PLACE_COUNTY,
  FLICKCURL_PLACE_REGION,
  FLICKCURL_PLACE_COUNTRY,
  FLICKCURL_PLACE_CONTINENT,
  FLICKCURL_PLACE_LAST = FLICKCURL_PLACE_CONTINENT
} flickcurl_place_type;

Place type

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

flickcurl_place_type type;

type enum ID

int id;

web service call ID

char *name;

name

flickcurl_place_type_to_id ()

int                 flickcurl_place_type_to_id          (flickcurl_place_type place_type);

Turn a place type into a place ID

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

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

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

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)

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)

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);

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

deprecated: Use flickcurl_places_placesForUser()

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);

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.

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.

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);

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.

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.

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

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)

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/

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)

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

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)

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)

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)

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)

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)

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)

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)

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