HowardsHome API – Documentatie 2017-12-19T12:47:52+00:00

Achtergrond

HowardsHome biedt een volwaardige API aan voor twee verschillende doelgroepen:

HowardsHome Search API.
Deze API biedt toegang tot alle door HowardsHome verzamelde content. Je kunt een zoekopdracht naar de API sturen en krijgt resultaten teruggeleverd.

HowardsHome Nieuws API.
Deze API is voor bestaande of nieuwe klanten die gebruik maken van HowardsHome Nieuws. In dit geval is er door de systemen van HowardsHome al een voorselectie van het nieuws gemaakt. De managementtools stellen een klant in staat om zeer specifieke zoekopdrachten in te stellen. Op basis van die zoekopdrachten wordt de content klaargezet. Met deze API kan je ook zoeken in het verzamelde archief.

Technische Achtergrond

oAuth
De API maakt gebruik van oAuth2 als authenticatiemechanisme. oAuth2 is een framework dat toegang geeft op basis van een externe authentication provider. Om gebruik te maken van de API kun je hier een account aanvragen. In overleg bepalen we dan welke mogelijkheden van onze API je het beste kunt gebruiken.

Meer weten over Oauth?

wiki page on oAuth
An introduction to oAuth2
The ‘hard’ ietf specs on oAuth2

Meer technische informatie over onze implementatie van oAuth vind je hier: https://assets.services.howardshome.com/docs/auth-api.html

REST API
Zodra de authenticatie is geregeld, is het mogelijk om de searchers aan te spreken.

Bij het endpoint /api/1/search kun je vier verschillende ‘searchers’ aanspreken:

NEWS – Hiermee zoek je in gekwalificeerde nieuwsbronnen. Er zijn hier een aantal extra zoekfaciliteiten en outputmogelijkheden die specifiek zijn voor het nieuws van HowardsHome dat gepreprocessed is: zogenaamde verrijkte output.
SOCIAL – Alle sociale bronnen. Forums, Facebook, comments, video, etc.
NEWSSOCIAL – Eén verzameling met de artikelen uit het nieuws, zonder de specifieke toevoeging en verrijking van HowardsHome Nieuws.
TWITTER – Alle Nederlandstalige Tweets.

Je kunt bij de query meerdere ‘views’ opgeven. Deze ‘views’ bepalen wat er met de gevonden resultaten gebeurt:

LIST – Een eenvoudige lijstweergave.
GROUPED – De resultaten worden gegroepeerd. Dit wordt gebruikt om te ontdubbelen.
CLUSTERED – Dit geeft een geclusterde weergave van de resultaten. Clustering gebeurt op basis van de inhoud van de documenten.
TOPS – Geeft een TOP X lijst voor je query, te gebruiken voor overzichtslijstjes.
TRENDS – Geeft het aantal resultaten per tijdsperiode weer.

Meer details over de Searchers vind je hier: https://assets.services.howardshome.com/docs/search-api-searchers.html

Voor de query (q=) kun je gebruikmaken van zoektermen, eventueel voorzien van Booleaanse algebra. Zo kun je bijvoorbeeld zoeken naar nieuws over overnames (q=”overname*”), maar niet als het over voetbal gaat: q=(“overname*” AND NOT voetbal)

Je kunt ook datumranges meegeven, deze dienen dan in dit format te zijn:

“dateFrom” : “2015-05-01T00:00:00+02:00”,

Een volledig request ziet er dan zo uit:

{
“searcher” : “NEWSSOCIAL”,
“view” : “LIST”,
“query” : “verstappen” ,
“dateFrom” : “2015-05-01T00:00:00+02:00”,
“dateTo” : “2015-05-08T00:00:00+02:00”,
}

Je zoekt hier naar nieuws over Verstappen, over de periode van een week.

Het resultaat hiervan komt terug in JSON:

{    “DocType”: “newssocial”,
“PublicationDate”: “2015-05-07T20:43:00Z”,
“Id”: “N1252955581”,
“Language”: “nl”,
“SentimentCode”: 1,
“Source”: “GP Pits”,
“Summary”: “Volgend op het nieuws van Renault dat de Fransen eerder dan gepland met een verbeterde motor komen, spreekt Max Verstappen zijn verwachting uit voor Spanje. Rémi Taffin van Renault Sport kwam met een vrij vaag statement: We komen met een gemodificeerde motor die ervoor moet zorgen dat de betrouwbaarheid en de ‘drivability’ de coureurs zal helpen om goede resultaten te behalen.. En Max Verstappen sprong daarop in, door te stellen dat een P7 wat hem betreft een prima resultaat zou zijn.”,
“Title”: “‘Max Verstappen wil P7 pakken'”,
“Url”: “http://www.gppits.net/nieuws/max_verstappen_wil_p7_pakken/”,
“UserName”: null,
“posted”: false,
“Channel”: “Sport”,
“ChannelId”: 6,
“Score”: 2.001199,
“ImageUrl”: null,
“Highlights”: [ “, spreekt Max Verstappen zijn verwachting uit voor Spanje. Rémi Taffin van Renault Sport kwam met een vrij” ],
“SourceId”: 34980,
“ContentType”: “News”,
“SourceAuthority”: null },

Meer details over de resultaten van andere searchers vind je hier: https://assets.services.howardshome.com/docs/search-api-result-object.html

Zoeken in HowardsHome Nieuws
Om in het verzamelde HowardsHome Nieuws te zoeken kun je gebruikmaken van de searcher NEWS. Om het nieuws uit één bestaand profiel op te halen, kun je bijvoorbeeld deze query opgeven: profile_id:123456.  Je geeft alleen een profile_id door en op basis daarvan krijg je alle artikelen die in dat profiel áán staan geleverd.

Let op, wij moeten er voor zorgen dat jouw account de juiste instellingen krijgt, zodat je het recht krijgt op toegang tot het HowardsHome Nieuws portal.

Testomgeving
Voordat je begint met de implementatie van de API, kun je alvast testen met de Sandbox. Dit is een Swagger omgeving waar je alle query’s  en mogelijkheden eenvoudig kunt testen: http://obelix.qa2.howardshome.com/swagger/ui/index Let op! je moet al een account van HowardsHome hebben ontvangen voor de API, om de resultaten te kunnen zien.

Alternatief: maak gebruik van ‘Postman’. Dit is een handige Google Chrome plugin waarmee je eenvoudig deze API test.

De volledige, uitgebreide technische documentatie vind je hier: https://assets.services.howardshome.com/docs/index.html