Mediahawk's new REST API
This is a quick step by step guide on how to migrate to using the new REST API. You will find a breakdown by method in the old API.
SOAP methods in REST
Most of the requests below return a collection of data that can be limited and paginated using the limit and offset parameters. By default these are set to 3000 and 0 respectively as they were in the SOAP API.
However, these values can be adjusted for your needs by including the parameters in your request. To find out whether an endpoint supports a limit and offset, please click on any of the paths in this guide to see the reference section.
The format of date parameters has changed. In the SOAP API you would pass in dates in DD/MM/YYYY format. However in the REST API dates are formatted as ISO 8601 without time (YYYY-MM-DD).
GetCallsById
To get calls by id you would have to make a request to the /calls endpoint and using the from_id parameter. This is the call id from where your data set will start. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/calls?api_key={apiKey}&from_id={callId}
GetCallsByDate
Getting calls by date requires calling the /calls endpoint with the from_date and to_date parameters included. This returns a set of call records for the given dates. The SOAP API request would return a set of call records on a given date whereas the REST API needs a to_date as well. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/calls?api_key={apiKey}&from_date={lowerDate}&to_date={upperDate}
GetCallByReference
To get a call by reference you would have to make a request to /calls/{callReference} and using the type parameter set to ref. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/calls/{callReference}?api_key={apiKey}&type=ref
GetCampaignIds
Previously in the SOAP API you could get all campaigns in one request.
First, request the static campaigns from the /campaigns endpoint. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/campaigns?api_key={apiKey}
Then, request dynamic URLs from the /urls endpoint. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/urls?api_key={apiKey}
To achieve a similar output as the SOAP API method, you would have to merge the results into one data set after calling the above endpoints.
GetDynamicCode
This method is called GetVisionCode in versions older than 1_9 of the SOAP API.
Requesting dynamic code instructions works slightly differently in the REST API. Currently you would have to pass the VA code of a dynamic URL then accessing the /instructions path. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/urls/{vaCode}/instructions?api_key={apiKey}
To find out the VA code of a dynamic URL, you would have to make a request to /urls to get a list of dynamic URL records. The resulting data set contains a property of va_code on each record. This can then be used to request the dynamic code instructions at /instructions.
GetDataByMHID
This method is called GetDataByMHRI in versions older than 1_9 of the SOAP API.
To get call data by MHID you would have to make a request to the /calls/{mhid} endpoint. The will require a MHID and a parameter of type set to mhid. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/calls/{mhid}?api_key={apiKey}&type=mhid
GetCtaById
To get CTA records using a CTA id as a starting point you would have to make a request to /ctas. This will require a parameter of from_id with the starting CTA id as its value. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/ctas?api_key={apiKey}&from_id={ctaId}
GetCtaByDate
To get a list of CTAs starting from a certain date you would have to make a request to /ctas with a from_date parameter. This date is where the data set will start from. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/ctas?api_key={apiKey}&from_date={fromDate}
GetVisitsById
To get a set of visit records using a visit id as a starting point you would have to make a request to /visits. This will require a parameter of from_id with a visit id where your data set starts from. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/visits?api_key={apiKey}&from_id={visitId}
GetVisitsByVisitorId
To get the visits of a visitor you will have to make a request to /visits with a parmeter of from_visitor_id. The visitor id value will filter the data set to contain only visits of a given visitor. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/visits?api_key={apiKey}&from_visitor_id={visitorId}
GetVisitsByDate
To get all visits for a given date you will have to make a request to /visits. This will require the from_date and to_date parameters. The value of both parameters is the date you require visit records for. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/visits?api_key={api_key}&from_date={date}&to_date={date}
GetPagesById
To get pages starting at a given page id you would have to make a request to /pages with a parameter of from_id. This is the page id value your data set will start from. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/pages?api_key={apiKey}&from_id={pageId}
GetPagesByVisitId
To get the pages of a visit you will have to make a request to /visits/{id}/pages with the query parmeter of {id} being the id of the visit you want to view pages for.
https://www.reports.mediahawk.co.uk/rest/v2_0/visits/{id}/pages
GetPagesByDate
To get all pages on a specific you will have to make a request to /pages with the from_date and to_date parameters. The parameters will contain the date you want page records for. For example:
https://www.reports.mediahawk.co.uk/rest/v2_0/pages?api_key={apiKey}&from_date={date}&to_date={date}