Developers
Python QuickStarts
This QuickStart will walk you through the basics of accessing the NewsCred Platform API using the Python programming language. Let's get started!
Downloading the Python API Wrapper
Start by downloading our Python API Wrapper. Once the download is completed, zip/tar it up and copy the newscred.py file to your application folder.
You'll need a valid API Access Key to make API calls in production, you can request one here. For development and testing purposes, you can use this API Access Key: c4bcc3f7c9bf9ec159f51da0a86ca658.
Understanding Modules
The NewsCred Platform API consists of 5 different modules, here's what they do:
Article Module - API methods for searching and retrieving content related to articles.
Category Module - API methods for searching and retrieving content related to categories.
Topic Module - API methods for searching and retrieving content related to topics.
Source Module - API methods for searching and retrieving content related to sources.
Author Module - API methods for searching and retrieving content related to authors.
Let's set things up by importing these modules in your application. It's also good practice to keep your API Access Key in a globally accessible variable like this:
from newscred import * access_key = 'c4bcc3f7c9bf9ec159f51da0a86ca658'
Working with Articles
Now that you're all set up, let's start making API calls!
Every object in the NewsCred Platform, except Category objects, is assigned a globally unique ID called a GUID.
We can retrieve an article by it's GUID like this:
# . . . # Get article by GUID guid = 'c0992a44a782ac65a4baf81cecfa8b4a' article = NewsCredArticle(access_key=access_key, guid=guid)
Now, let's retrieve related articles to this article by simply adding one line of code:
# . . . # Get related articles related_articles = article.get_related_articles()
Sometimes you won't know the GUID of the article you're searching for. For these cases, every module (except Category) comes with a handy search method. Let's add some code to search and retrieve articles matching the query "obama":
# . . . # Search articles query = 'obama' searched_articles = NewsCredArticle.search(access_key=access_key, query=query)
Filtering these search results is a piece of cake. All we have to do is pass in an optional dictionary of arguments like this:
# . . .
# Search articles with custom arguments
options = {}
options['offset'] = 0
options['pagesize'] = 10
options['from_date'] = '2009-07-01'
options['to_date'] = '2009-07-31'
options['sort'] = 'relevance'
options['sources'] = ['1ce0362f2e764a95b0c7351c05a4eb19', '2c20eeebd3486973559db5b654d87771']
options['source_countries'] = ['us', 'uk', 'in', 'qa', 'ca']
options['categories'] = ['world', 'u-k', 'u-s', 'sports', 'business', 'technology']
filtered_articles = NewsCredArticle.search(access_key=access_key, query=query, options=options)
For a complete guide to all our Article Module API methods, check out our API Reference.
Working with Categories
Next, let's explore categories.
The Category Module allows us to retrieve articles, images, topics and sources filtered by category. Categories don't have GUIDs. Instead, we use dashed names to identify them. Currently supported dashed category names are: "world", "u-s", "u-k", "europe", "asia", "technology", "business", "environment", "travel".
Let's write some code to retrieve a NewsCredCategory object:
# . . . # Get category by dashed name dashed_name = 'technology' technology = NewsCredCategory(access_key=access_key, name=dashed_name)
Now that we've retrieved the technology category object, we can use it to get technology related content like this:
# . . . # Get technology related articles technology_articles = technology.get_related_articles() # Get technology related topics technology_topics = technology.get_related_topics() # Get technology related sources technology_sources = technology.get_related_sources()
For more information about all our Category Module API methods, check out our API Reference.
Working with Topics
Now, let's take a look at topics.
The Topic Module let's us get related content by topic. It exposes a very powerful API that let's you easily retrieve articles, images, videos and more about different people, places, events, companies, organizations and products.
Let's start by retrieving the topic "Barack Obama" by it's GUID:
# . . . # Get Barack Obama topic by GUID obama_guid = '1e3f343e71de57fe9cc70b90c07e196e' obama = NewsCredTopic(access_key=access_key, guid=obama_guid)
Now we can quickly retrieve content related to Barack Obama like this:
# . . . # Get Barack Obama articles obama_articles = obama.get_related_articles() # Get Barack Obama images obama_images = obama.get_related_images() # Get Barack Obama videos obama_videos = obama.get_related_videos()
Next, lets retrieve other related topics to Barack Obama:
# . . . # Get topics related to Barack Obama obama_related_topics = obama.get_related_topics()
What if we only want to retrieve related people to Barack Obama? No problem. All topics are categorized into different topic classifications. Currently supported topic classifications are: "person", "place", "event", "company", "organization" and "product". So all we really need to do is add an optional filter argument like this:
# . . . # Get related people to Barack Obama options['topic_classifications'] = ['person'] obama_related_people = obama.get_related_topics(options=options)
Last but not least, for times when you don't know the topic GUID or simply want to find interesting topics, you'll come to love the topic search method:
# . . . # Search topics query = 'obama' searched_topics = NewsCredTopic.search(access_key=access_key, query=query)
For more information about Topic Module API Methods, check out our API Reference.
That's it! Thanks for taking this whirlwind tour of some of the basic features of the NewsCred Platform API.
What To Do Next
We've only scratched the surface of what's possible with the NewsCred Platform API in this QuickStart.
For next steps, we recommend that you take a look at our exhaustive API Reference with more than 150 code samples to get you off on the right track.
If you need any help getting started, have any questions or feedback, feel free to drop us a line at
platform@newscred.com anytime. Cheers!
