Our Search API is available by accessing a basic URL which is as follows and to which a few elements will need to be added for a complete query: http://www.ultimedia.com/api/search/search
Our API returns a list of standardised elements which can be either in XML or JSON format. In order to define the desired "datatype", you just have to insert in the URL one of the two following parameters:
datatype/xml
datatype/json
If you wish to obtain a file in XML format, your URL should therefore look like this
http://www.ultimedia.com/api/search/search/datatype/xml/
The "mdtk" parameter allows you to input the unique identifier of your site. This is visible on the Ultimedia platform in the Accounts / My sites / Sites list tab.
You just have to click on the "Edit" button corresponding to the site on which you wish to integrate the videos. The MDTK of your site is present at the top of the page of this editing form and is presented in the form of a series of 8 numbers.
This parameter must be filled in.
Example: http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567
The "zone" parameter is in the form of a number and allows you to define the zone of your site where the video will be integrated. This is usually the unitary integration zone.
If you are unsure of which zone number to use, please ask us. This parameter must be filled in.
Example: http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1
The " mode " parameter allows you to define the search mode to use. Here is a summary of how our 4 modes work:
Last: Displays the latest videos added to our platform, can be used with other filters such as the catalogue, the category or a keyword (filters detailed later in this document).
Top: Displays the most viewed videos on Ultimedia, can be used with other filters such as the catalogue, the category or a keyword (filters detailed later in this document).
Search: Displays the videos that contain all the keywords searched for, the videos are sorted by popularity for the current week + the previous week.
Smartlast: Displays the most relevant videos according to the keywords searched and favours the most recent results.
This parameter must be filled in.
Example: http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last
The "owner_id" parameter allows you to search only for videos from one or more of your catalogues. The unique identifier of each of your catalogues is available from the tab entitled "Rightsholder / Your catalogues / List of catalogues"
All you have to do is click on the "Edit" button corresponding to the catalogue you wish to search. The ID of your catalogue is displayed at the top of the page of this editing form and is a sequence of 5 letters and/or numbers.
If you wish to search multiple catalogues, simply separate each identifier with a comma.
Example: http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last/owner_id/12abc,34def
The "index" parameter allows you to search only for videos that are part of one or more of the defined video categories or sub-categories. A list of all the categories is available in the appendix of this documentation.
Here are the different filters that can be applied to the categories and sub-categories:
index/news,culture: Searches on one or more categories separated by a comma.
index/news,-culture: Allows you to exclude one or more categories from the search, always separating them by commas.
index/news!politics: Allows you to search on a sub-category only.
Example: http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last/owner_id/12abc,34def/index/news,business
The "q" parameter allows you to search on one or more words contained in the title of the videos.
You can search for several words at the same time by separating them with an underscore symbol "_".
Example:
http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last/owner_id/12abc,34def/index/news,business/q/syria_war
The "qtag" parameter allows you to search for a word or words contained in the tags of videos.
You can search for several words at the same time by separating them with an underscore symbol "_"
Note that this parameter is only available for the "last" and "top" modes and cannot be combined with the "q" search parameter.
Example:
http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last/owner_id/12abc,34def/index/news,business/qtag/syria_war
The "filter_date" parameter allows you to set a maximum date for video searches. This means that all videos with a publication date prior to the defined date will be searched for.
The release date of the video on which this parameter is based is the one communicated to us by the right-holder (release_time in the API response).
The date format to be used is: "dd-mm-yyyy".
By default, the date used is that of the current day.
Example:
http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last/owner_id/12abc,34def/index/news,business/q/war_syria/filter_date/21-06-2015
The "filter_interval" parameter is used to define the interval of the number of days over which to carry out the search and which must precede the "filter_date".
For example, if I use a filter_date set to 01-01-2000 associated with a filter_interval set to 365, the video search will be carried out between 01-01-1999 and 01-01-2000.
Example:
http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last/owner_id/12abc,34def/index/news,business/q/war_syria/filter_date/21-06-2015/filter_interval/30
The "date_after" parameter is an alternative to the use of "filter_date" and "filter_interval". It allows you to define a minimum date for searching for videos. This means that all videos with a publication date later than the specified date will be searched.
The publication date on which this parameter is based is the date of publication on our platform (creation_date or begin_time in the API response).
This filter expects a date in Unix "timestamp" format.
Example:
http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last/owner_id/12abc,34def/index/news,business/q/war_syria/date_after/1434844800
The "date_before" parameter is an alternative to the use of "filter_date" and "filter_interval". It allows you to define a maximum date for searching for videos. This means that all videos with a publication date before the specified date will be searched.
This filter expects a date in Unix timestamp format.
It can be used in conjunction with the "date_after" filter to define a very specific period between two dates.
For example, for a search between 21 June 2015 at 4pm and 30 June 2015 at 1pm:
http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last/owner_id/12abc,34def/index/news,business/q/war_syria/date_after/1434906000/date_before/1435672800
The "perpage" parameter is used to define the number of results to be displayed on each results page. The default value is set to 20 results.
We recommend values below 100 to ensure that queries are executed quickly.
If you need to display the following results, you just need to set the "page" parameter and indicate the page number to display.
Example:
http://www.ultimedia.com/api/search/search/datatype/xml/mdtk/01234567/zone/1/mode/last/owner_id/12abc,34def/index/news,business/q/war_syria/filter_date/21-06-2015/filter_interval/30/perpage/50/page/3
Once the API has been requested, you will get a list of various items related to each video that appear in the results. Here are the details of these items and what they do.
The <id> and <video_id> items tell you about the unique id of each video on our platform. The <id> item also contains a prefix that corresponds to the Digiteka theme ID. For example, if a video has a Digiteka id of "5krrkj" and is in the "News" category, its <id> will be "21_5krrkj".
These elements will generally not be useful to you, but may be useful in the case of using another Digiteka API.
The <content_type> element tells you the main theme of the video.
The <creation_date> element informs you about the date the video arrived on our platform. <update_date> corresponds to the date the video was last modified on the platform, if there have been no modifications <creation_date> = <update_date>.
<publication_date> is the date the video is available on our platform.
A video may have its availability date delayed from its creation date if the journalist chooses, for example, to make the video public only after a certain time.
The <title> element informs you about the title of the video. This is also the element of the video that the "q" search is performed on.
The <authors> element informs you about the name of the author of the video.
The <tags> element informs you about the tags or keywords associated with this video. Moreover, it is on this element of the video that the "qtag" search is performed.
The <description> element tells you about the description of the video. This is usually a short paragraph summarising the content of the video.
The <image>, <image_high>, <image_wide> elements allow you to retrieve four types of thumbnails for each video that offer resolutions of 134*100, 480*360, and 858*480 respectively for optimal display depending on the type of use you want to make. The <original_image> format offers a thumbnail in its original resolution as uploaded to our platform.
The <facebook> element allows you to retrieve a URL to insert in your metadata that will be useful for referencing the video as well as sharing it on the Facebook social network.
The <lengthvideo> element allows you to retrieve the length of the video. This length is expressed in seconds.
The <label> element allows you to retrieve the information of the catalog from which the video comes.
The <id_label> element allows you to retrieve the information of the catalog ID from which the video is taken. It is this ID that can be used in the previously mentioned "owner_id" parameter.
The <sub_categories> element allows you to retrieve the information of the sub-category to which the video is attached.
The <embed> and <iframe> elements allow you to retrieve the unit embed codes for each video either in javascript or iframe format.
These integration codes include the MDTK and the zone number inserted as parameters in the API request.
The <external_id> element tells you about the external ID of the video, this is the original ID of the video as it was sent to us by the client.
The <csa_rating> element tells you about the CSA rating level of the video.
The <id_sibling> element tells you the episode number and the season in the case of a series. It can also be the type and identifier of the Webedia work file in the case of a Webedia trailer.
The <in_stream> element informs you about the possibility of monetization of the video. If the field is 1, the video can be monetized, if it is 0, no ads can broadcast on this content.
The <credits> element contains two pieces of information: <owner> and <provider>.
These elements tell you about the "Owner" and "Provider" entities of the video.
The <local_target> element informs you about any restrictions on the territories for broadcasting the video. Geographic areas where video is allowed are provided in ISO format.
The <release_time> element corresponds to the date of the first broadcast of the video. For videos we receive from another platform, this is the date the video was posted on that first platform. The date here is in Unix timestamp format.
The <begin_time> and <end_time> elements correspond to the broadcast start and end dates for videos that are subject to an embargo and whose broadcast should only start broadcasting from a certain day and time and the same for the end of broadcast if necessary.
The <external_link> element tells you about the possible link that can be associated with the video, for example the URL of the article to which it is associated.
The <language_iso> element tells you about the nature of the main language of the video in ISO format
The <original_language> element tells you about the nature of the original language of the video (VF, VO, VOST)
Here is the complete list of Digiteka categories and sub-categories. The lines in bold correspond to the main categories, the sub-categories appear under their parent category.
|
Main category ID |
API names |
| 1 | music |
| frenchvariety | |
| 2 | cinema |
| cannes2013 | |
| cannes19972010 | |
| cannes | |
| cannes19601977 | |
| cannes19461959 | |
| cannes19781996 | |
| la-parisienne-a-cannes | |
| cinema | |
| 3 | travel |
| adventuretravel | |
| africa | |
| airtravel | |
| australianewzealand | |
| bedbreakfasts | |
| budgettravel | |
| businesstravel | |
| byuslocale | |
| camping | |
| canada | |
| caribbean | |
| cruises | |
| easterneurope | |
| europe | |
| france | |
| greece | |
| honeymoonsgetaways | |
| hotels | |
| italy | |
| japan | |
| mexicocentralamerica | |
| nationalparks | |
| southamerica | |
| spas | |
| themeparks | |
| travelingwithkids | |
| unitedkingdom | |
| 4 | sport |
| boating | |
| football | |
| cycling | |
| wintersports | |
| sailing | |
| tennis | |
| education | |
| athletics | |
| othersports | |
| formula1 | |
| rally | |
| golf | |
| basketball | |
| handball | |
| volleyball | |
| bmx | |
| rowing | |
| badminton | |
| ussport | |
| beachvolley | |
| wintersport | |
| boxing | |
| snowsports | |
| curling | |
| horseriding | |
| fencing | |
| sliding | |
| gymnastics | |
| weightlifting | |
| combatsports | |
| swimming | |
| figureskating | |
| sporttrack | |
| racketsports | |
| shooting | |
| 24hoursoflemans | |
| winterolympics | |
| summerolympics | |
| automoto | |
| rugby | |
| sports | |
| les-bleus | |
| tour-de-france | |
| coupe-du-monde-2014 | |
| hippisme | |
| psg-foot | |
| baseball | |
| bodybuilding | |
| canoeingkayaking | |
| cheerleading | |
| climbing | |
| cricket | |
| flyfishing | |
| freshwaterfishing | |
| gamefish | |
| inlineskating | |
| mountainbiking | |
| nascarracing | |
| paintball | |
| powermotorcycles | |
| proicehockey | |
| rodeo | |
| runningjogging | |
| saltwaterfishing | |
| scubadiving | |
| skateboarding | |
| skiing | |
| snowboarding | |
| surfingbodyboarding | |
| tabletennispingpong | |
| walking | |
| waterskiwakeboard | |
| 5 | cooking |
| americancuisine | |
| barbecuesgrilling | |
| cajuncreole | |
| chinesecuisine | |
| cocktailsbeer | |
| coffeetea | |
| cuisinespecific | |
| dessertsbaking | |
| diningout | |
| foodallergies | |
| frenchcuisine | |
| healthlowfatcooking | |
| italiancuisine | |
| japanesecuisine | |
| mexicancuisine | |
| vegan | |
| vegetarian | |
| wine | |
| 6 | people_old |
| 7 | multiple |
| 8 | women |
| 9 | howto |
| 10 | gardens |
| 11 | beauty |
| 12 | diy |
| 13 | health |
| medicinehealth | |
| sexo | |
| exercise | |
| a.d.d. | |
| aidshiv | |
| allergies | |
| alternativemedicine | |
| arthritis | |
| asthma | |
| autismpdd | |
| bipolardisorder | |
| braintumor | |
| cancer | |
| cholesterol | |
| chronicfatiguesyndrome | |
| chronicpain | |
| coldflu | |
| deafness | |
| dentalcare | |
| depression | |
| dermatology | |
| diabetes | |
| epilepsy | |
| gerdacidreflux | |
| headachesmigraines | |
| heartdisease | |
| herbsforhealth | |
| holistichealing | |
| ibscrohn?aosdisease | |
| incestabusesupport | |
| incontinence | |
| infertility | |
| nutrition | |
| orthopedics | |
| panicanxietydisorders | |
| pediatrics | |
| physicaltherapy | |
| psychologypsychiatry | |
| seniorhealth | |
| sleepdisorders | |
| smokingcessation | |
| substanceabuse | |
| thyroiddisease | |
| weightloss | |
| 14 | children |
| 15 | humor |
| 16 | tv |
| ardisson | |
| 17 | weather |
| 18 | motoring |
| auto | |
| moto | |
| autoparts | |
| autorepair | |
| buyingsellingcars | |
| carculture | |
| certifiedpreowned | |
| convertible | |
| coupe | |
| crossover | |
| diesel | |
| electricvehicle | |
| hatchback | |
| hybrid | |
| luxury | |
| minivan | |
| mororcycles | |
| offroadvehicles | |
| performancevehicles | |
| pickup | |
| roadsideassistance | |
| sedan | |
| trucksaccessories | |
| vintagecars | |
| wagon | |
| 19 | videogames |
| 20 | ads |
| various | |
| transportation | |
| medias | |
| culture | |
| hygiene | |
| fooddrink | |
| telecoms | |
| realestate | |
| clothing | |
| financeinsurance | |
| cleaningproducts | |
| servicecompanies | |
| 21 | news |
| economy | |
| international | |
| politics | |
| buzz | |
| africa | |
| middleeast | |
| asia | |
| france | |
| society | |
| archives | |
| geopolitics | |
| europe | |
| zapp | |
| business | |
| company | |
| diplomacy | |
| conflicts | |
| decolonization | |
| times | |
| dates | |
| warofalgeria | |
| coldwar | |
| indochineandvietnam | |
| nearandmiddleeast | |
| revolutions | |
| secondworldwar | |
| faitsdivers | |
| presidentialeducation | |
| presidentialecology | |
| presidentialcandidates | |
| presidentialhistory | |
| presidentialwork | |
| presidentialeconomy | |
| presidentialspots | |
| presidentialquotes | |
| presidentialduels | |
| presidentialeurope | |
| religion | |
| environnement | |
| art-de-vivre | |
| actu | |
| municipales-2014 | |
| ile-de-france-et-oise | |
| edito | |
| le-jour-ou | |
| presidentialsecurity | |
| presidentialretirement | |
| 22 | people |
| people | |
| 23 | deco |
| 24 | major |
| 25 | technology |
| web | |
| 3dgraphics | |
| animation | |
| antivirussoftware | |
| cc++ | |
| camerascamcorders | |
| cellphones | |
| computercertification | |
| computernetworking | |
| computerperipherals | |
| computerreviews | |
| datacenters | |
| databases | |
| desktoppublishing | |
| desktopvideo | |
| graphicssoftware | |
| homevideodvd | |
| java | |
| javascript | |
| macsupport | |
| mp3midi | |
| netconferencing | |
| netforbeginners | |
| networksecurity | |
| palmtopspdas | |
| pcsupport | |
| portable | |
| entertainment | |
| sharewarefreeware | |
| unix | |
| visualbasic | |
| webclipart | |
| webdesignhtml | |
| websearch | |
| windows | |
| 26 | home |
| gardens | |
| diy | |
| appliances | |
| entertaining | |
| environmentalsafety | |
| hometheater | |
| landscaping | |
| 27 | astro |
| 28 | business |
| bourse | |
| economy | |
| agriculture | |
| biotechbiomedical | |
| businesssoftware | |
| construction | |
| forestry | |
| government | |
| humanresources | |
| logistics | |
| marketing | |
| metals | |
| 29 | freaky |
| localnews | |
| 30 | culture |
| architecture | |
| show | |
| finearts | |
| literature | |
| museums | |
| loisirs-et-spectacles | |
| live | |
| musique | |
| 31 | masculin |
| 32 | fashion |
| bodyart | |
| jewelry | |
| clothing | |
| accessories | |
| 33 | lifestyle |
| arttechnology | |
| artscrafts | |
| beadwork | |
| birdwatching | |
| boardgamespuzzles | |
| candlesoapmaking | |
| cardgames | |
| chess | |
| cigars | |
| collecting | |
| comicbooks | |
| drawingsketching | |
| freelancewriting | |
| genealogy | |
| gettingpublished | |
| guitar | |
| homerecording | |
| investorspatents | |
| jewelrymaking | |
| magicillusion | |
| needlework | |
| painting | |
| photography | |
| roleplayinggames | |
| scrapbooking | |
| screenwriting | |
| stampscoins | |
| woodworking | |
| 34 | environnement |
| 35 | science |
| space | |
| earth | |
| life | |
| mathphysicschemistry | |
| socialsciences | |
| chemistry | |
| paranormalphenomena | |
| physics | |
| botany | |
| 36 | brands |
| 37 | family |
| adoption | |
| babiestoddlers | |
| daycarepreschool | |
| familyinternet | |
| parentingteens | |
| pregnancy | |
| specialneedskids | |
| eldercare | |
| 38 | celebrities |
| la-parisienne | |
| face-aux-lecteurs | |
| le-parisien-70ans | |
| 39 | equipment |
| 40 | education |
| geography | |
| history | |
| frenchliterature | |
| 712education | |
| adulteducation | |
| arthistory | |
| collegeadministration | |
| collegelife | |
| distancelearning | |
| englishasa2ndlanguage | |
| languagelearning | |
| graduateschool | |
| homeschooling | |
| homeworkstudytips | |
| k6educators | |
| privateschool | |
| specialeducation | |
| studyingbusiness | |
| 41 | entertainment |
| humor | |
| literaryadaptations | |
| animation | |
| fantasticandsf | |
| series | |
| historicalfictions | |
| crimestories | |
| telefilms | |
| theater | |
| 42 | media |
| tv | |
| advertising | |
| radio | |
| television | |
| 43 | archivesmusic |
| 44 | animals |
| aquariums | |
| birds | |
| cats | |
| dogs | |
| largeanimals | |
| reptiles | |
| veterinarymedicine | |
| 45 | religion |
| alternativereligions | |
| atheismagnosticism | |
| buddhism | |
| catholicism | |
| christianity | |
| hinduism | |
| islam | |
| judaism | |
| latterdaysaints | |
| paganwiccan | |
| 46 | careers |
| careerplanning | |
| college | |
| financialaid | |
| jobfairs | |
| jobsearch | |
| resumewritingadvice | |
| nursing | |
| scholarships | |
| telecommuting | |
| u.s.military | |
| careeradvice | |
| 47 | lawgovernmentpolitics |
| immigration | |
| legalissues | |
| u.s.governmentresources | |
| commentary | |
| 48 | personal finance |
| beginninginvesting | |
| creditdebtloans | |
| financialplanning | |
| hedgefund | |
| insurance | |
| investing | |
| mutualfunds | |
| options | |
| retirementplanning | |
| stocks | |
| taxplanning | |
| 55 | realestate |
| apartments | |
| architects | |
| buyingsellinghomes | |
| 56 | shopping |
| contestsfreebies | |
| couponing | |
| comparison | |
| engines | |
| 57 | nonstandardcontent |
| unmoderatedugc | |
| extremegraphicexplicitviolence | |
| pornography | |
| profanecontent | |
| hatecontent | |
| underconstruction | |
| incentivized | |
| 58 | illegalcontent |
| illegalcontent | |
| warez | |
| spywaremalware | |
| copyrightinfringement | |
| 92 | society |
| dating | |
| divorcesupport | |
| gaylife | |
| marriage | |
| seniorliving | |
| teens | |
| weddings | |
| ethnicspecific |