CORE APIs


The Core APIs (or more accurately, the Core Recommendation APIs) are the best starting point for learning the body of BeliefNetworks APIs. These APIs allow callers to write queries against data that BeliefNetworks has crawled from the Internet and from the Twitterverse. They require nothing more than writing your code (an api key is necessary to increase your daily query volume).

All APIs return data in XML format. Developers should understand the Core APIs before moving on to the Custom APIs and building custom corpora. For a conceptual understanding of Recommendations and Concepts and their importance to the input to and output from the APIs, please refer back to the Overview.

Contents


  • Recommend Concepts
  • Recommend Twitter Sites
  • Recommend Web Sites
  • Recommend Combined Sites

    • Recommend Concepts


    Description:

    Takes supplied text or a URL and provides a list of concepts back.

    Usage:


    HTTP VerbResource URL
    GET http://beliefnetworks.net/bnws/v1/recommendations/concepts?text=TEXT[&numresults=NUMBER]

    Where:


  • TEXT is a the text or URL you wish to extract.
  • NUMBER is the number of results you wish to have returned. The default is 35.

    • Output:

    <root>
  <recommendations>
    <recommendation weight="CONCEPTWEIGHT">CONCEPT</recommendation>
  </recommendations>
  ...

</root>

    Where:


  • CONCEPT is a concept discovered from the text or crawled site.
  • CONCEPTWEIGHT is a weight of the concept.

    • Examples:


  • Return the concepts for dog:
    GET http://beliefnetworks.net/bnws/v1/recommendations/concepts?text=dog
  • Return the concepts for the site http://cnn.com:
    GET http://beliefnetworks.net/bnws/v1/recommendations/concepts?text=http://cnn.com
  • Return the first 3 concepts for dog:
    GET http://beliefnetworks.net/bnws/v1/recommendations/concepts?text=dog&numresults=3

    • Recommend Twitter Sites


    Description:

    Takes supplied text or a URL and provides a list of Twitter sites that have similar concepts.

    Usage:


    HTTP VerbResource URL
    GET http://beliefnetworks.net/bnws/v1/recommendations/twitter-sites?text=TEXT[&numresults=NUMBER]

    Where:


  • TEXT is a the text or URL you wish to extract.
  • NUMBER is the number of results you wish to have returned. The default is 35.

    • Output:

    <root>
  <recommendations>
    <recommendation weight="SITEWEIGHT">TWITTERUSER</recommendation>
    <recommendationText>SAMPLESITETEXT</recommendationText>
  </recommendations>
  ...

</root>

    Where:


  • TWITTERUSER is a twitter user that has similar concepts as the text or site provided.
  • SITEWEIGHT is a weight of the twitter user relation to that text or site.
  • SAMPLESITETEXT a small sample of text from the twitter user.

    • Examples:


  • Return the twitter recommendations for dog:
    GET http://beliefnetworks.net/bnws/v1/recommendations/twitter-sites?text=dog
  • Return the twitter recommendations for the site http://cnn.com:
    GET http://beliefnetworks.net/bnws/v1/recommendations/twitter-sites?text=http://cnn.com
  • Return the first 3 twitter recommendations for dog:
    GET http://beliefnetworks.net/bnws/v1/recommendations/twitter-sites?text=dog&numresults=3

    • Recommend Web Sites


    Description:

    Takes supplied text or a URL and provides a list of web sites that have similar concepts.

    Usage:


    HTTP VerbResource URL
    GET http://beliefnetworks.net/bnws/v1/recommendations/web-sites?text=TEXT[&numresults=NUMBER]

    Where:


  • TEXT is a the text or URL you wish to extract.
  • NUMBER is the number of results you wish to have returned. The default is 35.

    • Output:

    <root>
  <recommendations>
    <recommendation weight="SITEWEIGHT">SITE</recommendation>
    <recommendationText>SAMPLESITETEXT</recommendationText>
  </recommendations>
  ...

</root>

    Where:


  • SITE is a URL for a web site that has similar concepts as the text or site provided.
  • SITEWEIGHT is a weight of the web site relation to that text or site.
  • SAMPLESITETEXT a small sample of text from the web site.

    • Examples:


  • Return the web site recommendations for dog:
    GET http://beliefnetworks.net/bnws/v1/recommendations/web-sites?text=dog
  • Return the web site recommendations for the site http://cnn.com:
    GET http://beliefnetworks.net/bnws/v1/recommendations/web-sites?text=http://cnn.com
  • Return the first 3 web site recommendations for dog:
    GET http://beliefnetworks.net/bnws/v1/recommendations/web-sites?text=dog&numresults=3

    • Recommend Combined Sites


    Description:

    Takes supplied text or a URL and provides a list of web sites and twitter users that have similar concepts.

    Usage:


    HTTP VerbResource URL
    GET http://beliefnetworks.net/bnws/v1/recommendations/combined-sites?text=TEXT[&numresults=NUMBER]

    Where:


  • TEXT is a the text or URL you wish to extract.
  • NUMBER is the number of results you wish to have returned. The default is 35.

    • Output:

    <root>
    <recommendations>
      <recommendation weight="SITEWEIGHT">SITE</recommendation>
      <recommendationText>SAMPLESITETEXT</recommendationText>
    </recommendations>
    ...

</root>

    Where:


  • SITE is a URL for a web site or a twitter user id that has similar concepts as the text or site provided.
  • SITEWEIGHT is a weight of the web site relation to that text or site.
  • SAMPLESITETEXT a small sample of text from the web site or twitter user id.

    • Examples:


  • Return the web site and twitter recommendations for dog:
    GET http://beliefnetworks.net/bnws/v1/recommendations/combined-sites?text=dog
  • Return the web site and twitter recommendations for the site http://cnn.com:
    GET http://beliefnetworks.net/bnws/v1/recommendations/combined-sites?text=http://cnn.com
  • Return the first 3 web site and twitter recommendations for dog:
    GET http://beliefnetworks.net/bnws/v1/recommendations/combined-sites?text=dog&numresults=3