Welcome! Below you can find useful information about how to receive Microsoft News content via the Microsoft News API that best fits your application experience.
Onboarding for Internal Testing of the Microsoft News API
Now that you have signed the Microsoft News API Evaluation Agreement, you are ready for onboarding.
Please answer the following questions and submit your responses to the Microsoft News Team Alias: MSFTNewsSupport@microsoft.com
1. Please briefly describe the user scenario where Microsoft News content will be integrated? Please provide a design mockup if available.
2. What specific types of content queries are you interested in?
3. What are the target markets?
4. What's the expected Query Per Second (QPS) for requests to the Microsoft News API?
Once responses have been received, the Microsoft News API team will send a set of specific parameters that have been assigned for your application. You'll be able to use these parameters to implement app authentication and track Microsoft News traffic generated by your app.
Feed End Point
The "Feed" endpoint is where you can get Microsoft News content in JSON format. Below is a sample query URL, with key parameters:
https://api.msn.com/news/Feed?ocid=<your_app>&market=en-us&query=entertainment&$top=100&$skip=0&$select=sourceid,type,url,provider,title,images,publishedDateTime,categories&apikey=<your_api_key>&user=<userid>&activityid=<activity_id>
ocid: A specific tracking code assigned for your app. You'll be assigned a unique OCID code after we’ve completed the onboarding process.
market: The locale ID of one of the Microsoft News available markets
query:
- If it matches a predefined category name in the local language, Microsoft News editorially curated content will be returned.
- If the query does not match a predefined category name, Microsoft News content will be returned by performing a search with the query string. Results will be returned based on relevancy of that string match to the content.
$top and $skip: These are the parameters used for paging through the content results.
$select: This parameter can specify what attributes to return in the response of the Microsoft News API call. This is useful if you wish to trim down the results of the API response to only a few fields.
apikey: This is to track the API request. A specific API key will be assigned for your app, after we’ve completed the onboarding process.
userid: Recommended user id format is {OCID}-{guid}.
- It needs to be anonymous (without any PII info).
- Consistent over time, in the requests of feed and user feedback endpoints.
- User can reset the user ID
activityid: A randomly generated guid for debugging purposes. (GUID is an acronym for 'Globally Unique Identifier'. It is a 128-bit integer number, e.g. 9a651f95-46b4-4996-8416-9a6900ea62f9.
Personalization
Microsoft News API has the capability of providing personalized feeds. To get personalized news feed you can put “user” parameter on /feed or full page API endpoints:
1. The calling pattern of feed endpoint to get personalized “my feed” is:
https://api.msn.com/news/feed?market=en-us&$top=10&queryType=myFeed&activityId={Activity ID}&ocid={OCID}&user={user id}&apikey={api key}
2. The User ID needs to be:
- Anonymous, without any PII info
- Consistent over time, in the requests of feed and user feedback endpoints
- User can reset the user ID
User ID format: OCID + "-" + GUID
3. Note - if the personalized API requests are not being sent directly from user devices but proxy'ed via server-to-server call:
- The server-to-server requests to Microsoft News services need to forward the IP address of the device
- End-user's IP address needs to be added into the standardized XFF header
- This is to avoid Azure Frontdoor throttling on the requests for potential DOS attack.
4. In the feed & fullpage API response, you can find callback URLs for clicks/impressions, you will need to call this callback URLs to send back signals for personalization.
- clickFeedbackUrl
- impressionFeedbackUrl
Feel free to let us know if you have any questions. We look forward to working with you!