Photo Recommendations

The API recommends photos for an article, using multiple strategies, and supporting both strict constrains and soft preferences, such as age, format, licence, entities mentioned in the caption, etc.

We will first define some common code (replace <YOUR_API_KEY> with your API key):

No special setup necessary

Supported Photo Banks

First, we need to see which photo banks are available for a given API Key:

curl -X GET -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'http://media-api.geneea.com/v2/photos'

["ctk", "demo", "shutterstock"]

Recommendation

We will pick the ctk dataset and recommend photos for the same text as above. The text of the article is submitted in the same way as in semantic tagging: either via title and text fields or using the paraSpecs array (see here).

curl -X POST -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'http://media-api.geneea.com/v2/photos/ctk/recommend' -d '{
    "id": "1234",
    "title": "Emmanuel Macron in Germany.",
    "text": "Mr. Macron visited a trade show in Munich.",
    "recommendationCount": 2,
    "returnObjects": true,
    "returnObjectFields": ["name", "description", "url"]
}'

Here is the simplified output:

{
  "id": "1234",
  "referenceKey": "211023-183731-e073c8c0",
  "photosIds": [ "P2021102202885", "P201904290731201" ],
  "photos": [
    {
      "id": "P2021102202885",
      "description": {
        "en": "French President Emmanuel Macron arrives ..."
      },
      "name": { "cs": "Emmanuel Macron" },
      "url": "http://imultimedia.ctk.cz/storage/foto/P2021102202885/515x515.wm/P2021102202885.jpeg"
    },
    {
      "id": "P201904290731201",
      "description": {
        "en": "German Chancellor Angela Merkel welcomes President of France Emmanuel Macron ..."
      },
      "name": { "cs": "Emmanuel Macron, prezident, politik, Angela Merkel ..." },
      "url": "http://imultimedia.ctk.cz/storage/foto/P201904290731201/515x515.wm/P201904290731201.jpeg"
    }
  ],
  "nextCursor":"5bd1c54c12d5070c",
  "tags": [
    {"type": "Geneea", "value": "G3052772", "subType": "person", "description": "Emmanuel Macron (G3052772)", "score": 21.8421387408},
    {"type": "Geneea", "value": "G567", "subType": "person", "description": "Angela Merkel (G567)", "score": 12.1114189616},
    {"type": "Geneea", "value": "G458", "subType": "organization", "description": "European Union (G458)", "score": 14.5874189616},
    {"type": "Geneea", "value": "G64", "subType": "location", "description": "Berlin (G64)", "score": 18.2413894616}
  ]
}

The output is mostly self-explanatory. Tags can be used to further filter the results; see Constraints below.

Paging

To page through the results, the request must contain an empty cursor ('cursor': '*'):

curl -X POST -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'http://media-api.geneea.com/v2/photos/ctk/recommend' -d '{
    "id": "1234",
    "title": "Emmanuel Macron in Germany.",
    "text": "Mr. Macron visited a trade show in Munich.",
    "recommendationCount": 2,
    "returnObjects": true,
    "returnObjectFields": ["name", "description", "url"],
    "cursor": "*"
}'

The response then contains a cursor (nextCursor):

{
  "id": "1234",
  "referenceKey": "241013-200942-a453cdba",
  "photosIds": ["P2022100611159", "P201906200639001"],
  "photos": [
    {
      "id": "P2022100611159",
      "description": {"en": "French President Emmanuel Macron attends a news conference at the end of the first day of the European Political Community (EPC), new political grouping at the Prague Castle, Czech Republic, on October 6, 2022. (CTK Photo/Vit Simanek)"},
      "name": {"en": "Emmanuel Macron"},
      "url": "https://fotoarchiv.ctk.cz/geneea/preview/P2022100611159"
    },
    {
      "id": "P201906200639001",
      "description": {"en": "French President Emmanuel Macron comes to an EU summit, on June 20, 2019, in Brussels, Belgium. (CTK Photo/Jakub Dospiva)"},
      "name": {"en": "Emmanuel Macron"},
      "url": "https://fotoarchiv.ctk.cz/geneea/preview/P201906200639001"
    }
  ],
  "tags": [
    { "type": "Geneea", "value": "G3052772", "subType": "person", "description": "Emmanuel Macron", "score": 23.6842774816 },
    { "type": "Geneea", "value": "G193369", "subType": "location", "description": "Prague Castle", "score": 4.9733127066 },
    { "type": "Geneea", "value": "G239", "subType": "location", "description": "Brussels", "score": 4.904134278 },
    { "type": "Geneea", "value": "G458", "subType": "organization", "description": "European Union", "score": 4.0557094808 },
    { "type": "Geneea", "value": "G272281", "subType": "general", "description": "news conference", "score": 3.3702637114 },
    { "type": "Geneea", "value": "G31", "subType": "location", "description": "Belgium", "score": 2.3611396911 },
    { "type": "Geneea", "value": "G82955", "subType": "general", "description": "politician", "score": 1.7318228339 },
    { "type": "Geneea", "value": "G30461", "subType": "general", "description": "president", "score": 1.4457626534 },
    { "type": "Geneea", "value": "G113834800", "subType": "organization", "description": "European Political Community", "score": 1.0 },
    { "type": "Geneea", "value": "G213", "subType": "location", "description": "Czechia", "score": 0.8172601547 }
  ],
  "nextCursor": "5bd1c54ce2dc64f9"
}

Constraints

The API supports constraining the results in various ways:

  • requiring photos to be shot at certain dates

  • requiring an entity to be mentioned in photo caption or title

  • requiring an entity not to be mentioned in photo caption or title

See the API reference for more detail.

More like this

An ID of a photo from a recent search can be passed as the parameter of the likePhotoId constraint. A new recommendation is performed searching for similar photos.

curl -X POST -H 'X-API-KEY: <YOUR_API_KEY>' -H 'accept: */*' -H 'content-type: application/json' 'http://media-api.geneea.com/v2/photos/ctk/recommend' -d '{
    "id": "1234",
    "title": "Emmanuel Macron in Germany.",
    "text": "Mr. Macron visited a trade show in Munich.",
    "recommendationCount": 2,
    "returnObjects": true,
    "returnObjectFields": ["name", "description", "url"],
    "constraints": {
        "likePhotoId": "P201904290731201"
    },
}'