{ "info": { "author": "Stijn Debrouwere", "author_email": "stijn@debrouwere.org", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.4", "Topic :: Scientific/Engineering :: Information Analysis" ], "description": "``facebook-insights`` is a command-line utility that makes it easier to\ninteract with `Insights metrics in the Facebook Graph\nAPI `__.\nPython users can also directly access the API wrapper that the CLI is\nbuilt on.\n\n- **Authentication.** OAuth2 is a bit of a pain and we've made it\n easier.\n- **Querying.** Query page and post insights with simple command-line\n parameters or through a pythonic interface.\n- **Reporting.** Outputs simple timeseries of the data rather than\n verbose API responses.\n- **Portability.** JSON output means you can analyze the data in any\n language from R to Julia to Ruby to Java.\n\n**Development status:** the Python interface to ``facebook-insights`` is\nclose to stable, but some things might change and others still need\npolish. The command-line interface is still very much a work in progress\nand you probably shouldn't try to use it yet.\n\nUsage\n-----\n\nAuthentication\n^^^^^^^^^^^^^^\n\n.. code:: python\n\n import os\n import facebookinsights as fi\n\n # prompt for credentials on the command-line, \n # get access to one or more pages\n pages = fi.authenticate()\n # alternatively, pass an existing page token\n page = fi.authenticate(token=os.environ['FACEBOOK_PAGE_TOKEN'])\n\nScroll down to find out more about authentication.\n\nPage Posts\n^^^^^^^^^^\n\nFacebook provides Insights data for the page as a whole (follower\ncounts, impressions across all stories etc.), for all page posts taken\ntogether (likes for all page posts published last week etc.) and for\nindividual posts (video plays for one particular post etc.)\n\n.. code:: python\n\n # return a range of page posts\n latest = page.posts.latest(10).get()\n today = page.posts.range(days=1).get()\n quarter = page.posts.range(months=3).get()\n\n # look for a particular post instead\n page.posts.find(url='http://fusion.net/story/37894/narcotrafficking-for-dummies-check-out-these-pics-of-bizarre-drug-smuggling-fails/')\n\nReporting Periods\n^^^^^^^^^^^^^^^^^\n\nFor many metrics, Facebook Insights includes historical data, so you can\nsee e.g. how your page's fans have increased or decreased over time.\nHowever, for some page metrics and most post metrics, only lifetime\nmetrics are available, which represent the current state of things.\n\n.. code:: python\n\n # for many metrics, historical data is available, with daily, weekly \n # and 4-weekly rollups, accessible through `daily`, `weekly` and \n # `monthly` methods\n page.insights.daily(['page_impressions', 'page_fan_adds']).range(months=1).get()\n # for other metrics, there's only a lifetime total\n post.insights.lifetime('post_stories').get()\n # for some, it's the other way around: no total, only the daily numbers\n for country_data in page.insights.daily('page_places_checkins_by_country'):\n print country_data\n\nAlso note that some metrics are updated roughly every 15 minutes whereas\nothers can lag behind up to a day. Metrics postfixed with an asterisk in\nthe `Facebook Graph API\ndocumentation `__\nindicate frequently updated metrics.\n\n**Note:** currently, ``facebook-insights`` will not throw an error if\nyou ask for a metric at an impossible granularity. Instead, Facebook\nwill return data at the granularity (often lifetime) that it can\nprovide.\n\nMetrics\n^^^^^^^\n\nIt is possible to ask for one or more metrics in particular.\n\n.. code:: python\n\n # results will be returned as a single scalar value\n page.insights.lifetime('page_impressions').get()\n # results will be returned as an array\n page.insights.lifetime(['page_impressions', 'page_fan_adds']).get()\n # default metrics subset\n page.insights.lifetime().get()\n\nIf no metrics are specified, the Facebook Graph API will return a useful\nsubset by default.\n\nQuery Results\n^^^^^^^^^^^^^\n\n.. code:: python\n\n # metrics are classless, rows are named tuples\n # column plucking is possible\n post.lifetime()[0].page_fans\n post.daily()['page_fans'][0]\n post.daily('page_fans')[0]\n\nLower-level\n^^^^^^^^^^^\n\n``facebook-insights`` is built on the\n`FacePy `__ library, and you may pass\ncertain low-level options to FacePy when executing queries:\n\n.. code:: python\n\n post.daily('page_fans_online_per_day', retry=3)\n\nTerminology\n-----------\n\n- **page**: a Facebook (fan) page\n- **page post**: a post to a Facebook page\n- **story**: a user interaction with a page, e.g. \"Mike liked this\n page.\" or \"Jeb shared this post with his friends.\"\n- **story type**: the type of interaction a user has with a page, e.g.\n a checkin, a mention or a like.\n- **storyteller**: a user who interacts with a page (e.g. by liking a\n page post)\n- **impression**: a view of either the page or a page post\n- **engaged user**: a user who clicked anywhere on a page or a page\n post\n- **consumption**: a click on a page or a page post; an engaged user\n can show up as one or more consumptions\n- **fan**: a user who has liked your page and will usually see it in\n their feed. Similar to a Twitter follower.\n- **unique**: count no more than once per user\n- **organic**: impressions or interactions not the result of promoting\n your post, as opposed to paid impressions and interactions\n- **feedback**: positive feedback includes likes, shares and so on;\n negative feedback includes hiding, unliking and reporting spam.\n\nMost of this terminology applies both at the page level and at the page\npost level. For example:\n\n- ``page_impressions_unique`` at the page level\n- ``page_posts_impressions_unique`` for interactions with any page post\n- ``post_impressions_unique`` about one particular post\n\nYou will find more detailed explanations of much of this terminology and\na list of all story and feedback types in the `Facebook Graph API\nInsights\ndocumentation `__,\nwhich is excellent.\n\nPage and Post objects\n---------------------\n\nPending better documentation, to find out more about what properties and\nmethods are available on ``Page``, ``Post``, ``Picture`` objects, please\ntake a look at ``facebookinsights/graph.py``.\n\nTo find out more detailed information about querying, look at\n``Selection``, ``PageSelection`` and ``InsightsSelection`` in\n``facebookinsights/graph.py``.\n\nAuthentication in detail\n------------------------\n\nYou cannot use the Facebook Graph API with your Facebook username and\npassword. Instead, you must authenticate through oAuth, first getting a\nuser access token and then using that token to find the access tokens to\nthe Facebook Pages for which you are an admin or for which you otherwise\nhave permission to view the insights data.\n\nShort-term\n~~~~~~~~~~\n\nShort term access (a couple of hours) is most easily gained through the\n`Graph API Explorer `__.\n\n1. Go to the `Graph API\n Explorer `__\n2. Click on ``Get Access Token`` near the top of the page\n3. Navigate to the ``me/accounts`` endpoint by entering it and clicking\n submit\n4. Find and copy the page access token or tokens from the resulting JSON\n\nOn the command line:\n\n.. code:: sh\n\n # WARNING: suggested interface, not built yet\n # use a token on every request\n insights posts \\\n --token \\\n --since 2014-08-01 \\\n --until 2014-08-10 \\\n --metrics post_impressions\n # use a saved token from a `~/.facebookinsights` \n # INI file instead\n insights posts \\\n --profile \n\nIn Python:\n\n.. code:: python\n\n import facebookinsights as fi\n page = fi.authenticate(token='your page token goes here')\n\nLong-term\n~~~~~~~~~\n\nIt is also possible to ask Facebook for page tokens that remain valid\nindefinitely unless revoked by the page owner.\n\n1. Go to the `Facebook Developers `__\n portal, and click on ``Apps > Create a New App``\n2. Fill out the requisite information\n3. After being redirected to your app's settings page, grab the App ID\n and App Secret. Save them somewhere, e.g. as environment variables in\n your ``~/.bashrc``\n4. Go to advanced settings and specify that your app is a\n ``Native or desktop app``\n5. Lower down on the advanced settings page, add\n ``http://localhost:5000/`` to the Valid OAuth redirect URIs.\n\nIf you intend to make your app public at some point, there are various\nother steps to go through: whitelisting callback URLs, going through the\nFacebook app approval process and so on.\n\nIf on the other hand you just want to analyze your own Facebook Insights\ndata, you'll probably never need to look at your app settings again.\n\nOn your desktop\n^^^^^^^^^^^^^^^\n\nOn the command-line, get authorization and save the resulting page\ntokens:\n\n.. code:: sh\n\n # WARNING: suggested interface, not built yet\n # provide client_id and client_secret\n insights auth \n # use a profile from a `~/.facebookinsights` \n # INI file instead\n insights auth --profile \n\nIn Python:\n\n.. code:: python\n\n import facebookinsights as fi\n # this will launch a web browser to authenticate\n pages = fi.authenticate(\n client_id='your client id', \n client_secret='your client secret', \n )\n\nIf no arguments to ``authenticate`` are specified, ``facebook-insights``\nwill look for environment variables named\n``FACEBOOK_INSIGHTS_CLIENT_ID`` and ``FACEBOOK_INSIGHTS_CLIENT_SECRET``\nwhich correspond to the App ID and App Secret you got from your app's\nsettings page earlier.\n\n.. code:: python\n\n import facebookinsights as fi\n # this will launch a web browser to authenticate\n pages = fi.authenticate()\n\n``pages`` will be a list of ``Page`` objects. You can access a page's\ntoken with ``page.token``, which means you can make save those tokens\nfor later use. This is especially important for analyses and other code\nthat runs unattended, as getting new tokens through an oAuth\nauthorization process always requires user interaction.\n\nHere's an example that uses your system's keychain to store credentials:\n\n.. code:: python\n\n import keyring\n import json\n import facebookinsights as fi\n\n token = keyring.get_password('facebook-insights', 'test')\n if token:\n page = fi.authenticate(token=token)\n else:\n page = fi.authenticate()[0]\n keyring.set_password('facebook-insights', 'test', page.token)\n\nIn a web app\n^^^^^^^^^^^^\n\nAn example of how to integrate Facebook oAuth authorization in a Flask\nweb app is provided in ``examples/server.py``. The process is very\nsimilar for Django and other Python web frameworks:\n\n- One route that redirects to Facebook\n- Another route that receives the authorization code from Facebook and\n exchanges it for a user token and subsequently for page tokens", "description_content_type": null, "docs_url": null, "download_url": "http://www.github.com/debrouwere/facebook-insights/tarball/master", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "UNKNOWN", "keywords": "data analytics api wrapper facebook insights", "license": "ISC", "maintainer": null, "maintainer_email": null, "name": "facebookinsights", "package_url": "https://pypi.org/project/facebookinsights/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/facebookinsights/", "project_urls": { "Download": "http://www.github.com/debrouwere/facebook-insights/tarball/master", "Homepage": "UNKNOWN" }, "release_url": "https://pypi.org/project/facebookinsights/0.3.4/", "requires_dist": null, "requires_python": null, "summary": "A wrapper and command-line interface for the Facebook Insights API.", "version": "0.3.4" }, "last_serial": 1633548, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "5a3f9257e43311374b90162783f210f9", "sha256": "f396c9525b6da7e3989e9f68f65a6597ceb802dc554e44faa68d6fd9f96e5f87" }, "downloads": -1, "filename": "facebookinsights-0.1.0.tar.gz", "has_sig": false, "md5_digest": "5a3f9257e43311374b90162783f210f9", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10218, "upload_time": "2014-11-05T20:13:14", "url": "https://files.pythonhosted.org/packages/14/3f/1c6541beb754202a24560965eee015eb88aa124b169b4f80cf44cd7a63c4/facebookinsights-0.1.0.tar.gz" } ], "0.1.1": [ { "comment_text": "", "digests": { "md5": "27c879d4c6447f77b97820793a30392c", "sha256": "0d8dfed7f1c34e7cab4759a18173c4737a421b8446737ca88213e52aeb2c4ec7" }, "downloads": -1, "filename": "facebookinsights-0.1.1.tar.gz", "has_sig": false, "md5_digest": "27c879d4c6447f77b97820793a30392c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10297, "upload_time": "2015-01-13T16:00:51", "url": "https://files.pythonhosted.org/packages/ea/ea/06bd8b0c8991051df66ec00b8fb9ce14cc49fe90bd5ffe2d0643d45dbcef/facebookinsights-0.1.1.tar.gz" } ], "0.1.2": [ { "comment_text": "", "digests": { "md5": "4d205c26a91fadc91c0a8a6cea01a1af", "sha256": "33729594397a9bdadd0ed9b191323d9e2d4fd06acef77fa135d0969f7aa9e9c6" }, "downloads": -1, "filename": "facebookinsights-0.1.2.tar.gz", "has_sig": false, "md5_digest": "4d205c26a91fadc91c0a8a6cea01a1af", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10704, "upload_time": "2015-01-13T17:10:17", "url": "https://files.pythonhosted.org/packages/f6/86/82c267007df4867383d6bfd68b723c294e60044229003987cf4decaec0ab/facebookinsights-0.1.2.tar.gz" } ], "0.1.3": [ { "comment_text": "", "digests": { "md5": "05590d0d7dfe3944f8ab1e0ff454de73", "sha256": "c9d0ca7f4deffe562d8a1ecad6c0265bfb57ebea1075976309950824ff4e204f" }, "downloads": -1, "filename": "facebookinsights-0.1.3.tar.gz", "has_sig": false, "md5_digest": "05590d0d7dfe3944f8ab1e0ff454de73", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10717, "upload_time": "2015-01-13T17:40:03", "url": "https://files.pythonhosted.org/packages/0c/42/c5ef0c35ed143e7b6f7c1d7c1fa72134cbf6b219f154abefb690c23ccd6a/facebookinsights-0.1.3.tar.gz" } ], "0.1.5": [ { "comment_text": "", "digests": { "md5": "8cb76cfe04071fa7a9344c1d830697f5", "sha256": "d6d2a54da0d890234373b47f661fba92612661f946aa79cda97c4e5b7805482c" }, "downloads": -1, "filename": "facebookinsights-0.1.5.tar.gz", "has_sig": false, "md5_digest": "8cb76cfe04071fa7a9344c1d830697f5", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13672, "upload_time": "2015-01-13T21:52:38", "url": "https://files.pythonhosted.org/packages/b1/4c/a32b7515d45cd97e791423ef29c9eba87116e7a90faef73b991fa44f6281/facebookinsights-0.1.5.tar.gz" } ], "0.3.0": [ { "comment_text": "", "digests": { "md5": "605c7439bc2e0c250009aff9df5f31ee", "sha256": "d458f905d60c479540847bccec8bbfe7585329c96e740c53e506b54b274799a7" }, "downloads": -1, "filename": "facebookinsights-0.3.0.tar.gz", "has_sig": false, "md5_digest": "605c7439bc2e0c250009aff9df5f31ee", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14210, "upload_time": "2015-02-04T20:52:20", "url": "https://files.pythonhosted.org/packages/2a/56/6feebafd1192fb48e0da7e9618550b22354633e3ef6741c22b038996e539/facebookinsights-0.3.0.tar.gz" } ], "0.3.1": [ { "comment_text": "", "digests": { "md5": "a8c95c028df8d073ff59a6b9a95e54be", "sha256": "1d1bca3b6734a11292eb1c052cc714e4191ed7a8a2f9e4876013ac39366cc1d4" }, "downloads": -1, "filename": "facebookinsights-0.3.1.tar.gz", "has_sig": false, "md5_digest": "a8c95c028df8d073ff59a6b9a95e54be", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14205, "upload_time": "2015-03-26T22:06:11", "url": "https://files.pythonhosted.org/packages/36/ec/94e07296b8df9d1fe542ff7dd2f8344606a743c44e50504dad0e350e3d4b/facebookinsights-0.3.1.tar.gz" } ], "0.3.2": [ { "comment_text": "", "digests": { "md5": "f1410ece351318a31e1da12bf96ad17c", "sha256": "a67a2660f66cd9f41a07be6070acd064871e851ed822de5d86dbee7d26eb4bc3" }, "downloads": -1, "filename": "facebookinsights-0.3.2.tar.gz", "has_sig": false, "md5_digest": "f1410ece351318a31e1da12bf96ad17c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 14240, "upload_time": "2015-06-25T17:56:57", "url": "https://files.pythonhosted.org/packages/56/f7/2306ae652f1c14db6b94128192880022798d342ec05bf6b3711888080b6b/facebookinsights-0.3.2.tar.gz" } ], "0.3.3": [ { "comment_text": "", "digests": { "md5": "3ac6c4e059b22f87055498a7c30eec60", "sha256": "0d34ccc5a539265b3911bc55af74a88cd3909514435e205826dbd6a0d5d840c5" }, "downloads": -1, "filename": "facebookinsights-0.3.3.tar.gz", "has_sig": false, "md5_digest": "3ac6c4e059b22f87055498a7c30eec60", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15352, "upload_time": "2015-06-27T16:24:33", "url": "https://files.pythonhosted.org/packages/e7/83/bc276e5b566cfbeb5c964f4331beb4b762af38c0f57a930c1c935d284082/facebookinsights-0.3.3.tar.gz" } ], "0.3.4": [ { "comment_text": "", "digests": { "md5": "89fa22ac3429d485b373e8956757c318", "sha256": "ee6c2b739a4886546db499da8a271f3885527dc65070f77a6ef409895eefe460" }, "downloads": -1, "filename": "facebookinsights-0.3.4.tar.gz", "has_sig": false, "md5_digest": "89fa22ac3429d485b373e8956757c318", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15417, "upload_time": "2015-07-14T21:35:36", "url": "https://files.pythonhosted.org/packages/44/fe/385c9a655d699732b091e9090515921c59efd6ad869555ce0ae1418fa498/facebookinsights-0.3.4.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "89fa22ac3429d485b373e8956757c318", "sha256": "ee6c2b739a4886546db499da8a271f3885527dc65070f77a6ef409895eefe460" }, "downloads": -1, "filename": "facebookinsights-0.3.4.tar.gz", "has_sig": false, "md5_digest": "89fa22ac3429d485b373e8956757c318", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15417, "upload_time": "2015-07-14T21:35:36", "url": "https://files.pythonhosted.org/packages/44/fe/385c9a655d699732b091e9090515921c59efd6ad869555ce0ae1418fa498/facebookinsights-0.3.4.tar.gz" } ] }