{ "info": { "author": "Dan Goodman", "author_email": "dgoodman@conductor.com", "bugtrack_url": null, "classifiers": [], "description": "# searchlight-api-client-python\n![Latest Version](https://img.shields.io/pypi/v/searchlight-api.svg)\n\nThe Searchlight API Client is a Python package that makes it easy to authenticate with and retrieve data from the Conductor Searchlight API.\n\n## Getting Started\n\n### Installation\n\nThe latest released version can be installed through the Python package index.\n\n```\npip install searchlight-api\n```\n\n### Dependencies\n\n* [Requests](http://docs.python-requests.org/en/master/): 2.19.1 or higher\n* [Simplejson](https://simplejson.readthedocs.io/en/latest/): 3.11.1 or higher\n\n### Authentication\nThe Searchlight API Client needs to know your API Key and API Secret to authenticate with Searchlight. It can find these in one of two ways:\n* Add the credentials to your environmental variables (preferred)\n * MacOS / Linux: Edit your .bash_profile to include the lines\n * export SEARCHLIGHT_API_KEY=xxxxx\n * export SEARCHLIGHT_SHARED_SECRET=xxxxxx\n * Windows: Add SEARCHLIGHT_API_KEY and SEARCHLIGHT_SHARED_SECRET in the [Environment Variables in the Advanced system settings](https://docs.microsoft.com/en-us/windows/desktop/procthread/environment-variables)\n* Pass the credentials when instantiating the API Client\n from searchlight_api.client import AccountService\n account_service = AccountService(api_key=xxxxx, secret=xxxxx)\n\nIf you don't have an API Key and Secret, request one from http://developers.conductor.com/. You should receive an email within a week containing your credentials.\n\n### Using searchlight_api\n\nThe Searchlight API Package has two main functionalities: client and analysis\n* client provides an SDK around the Searchlight REST API, making it easy to request the data that you need from your accounts.\n* analysis includes functions for aggregating data (Rank and Search Volume) using the Searchlight API.\n\n#### Examples\n\n##### Client\n\n###### SearchlightService\nThe SearchlightService client provides wrappers for getting Searchlight and profile configuration data\n```\nfrom searchlight_api import client\n\n# instantiate Searchlight client\nss = client.SearchlightService()\n# Retrieve all Searchlight accounts you have access to.\n# You can use this to retrieve Account IDs to instantiate the AccountService client\n\nmy_accounts = ss.get_accounts()\nprint(my_accounts)\n[{'accountId': 'XXXX',\n 'isActive': False,\n 'name': 'Account 1',\n 'webProperties': 'https://api.conductor.com/v3/accounts/XXXX/web-properties'},\n {'accountId': 'YYYY',\n 'isActive': True,\n 'name': 'Account 2',\n 'webProperties': 'https://api.conductor.com/v3/accounts/YYYY/web-properties'}]\n\n# Account IDs can also be found in Searchlight URLs: https://searchlight.conductor.com/YYYY/insight-stream\n```\n\nIn Searchlight, keywords can be tracked across different Rank Sources (or Search Engines), Locations and Devices.\nYou can retrieve what's supported with the following:\n\n```\nrank_sources = ss.get_rank_sources()\nlocations = ss.get_locations()\ndevices = ss.get_devices()\n```\n\n###### AccountService\nThe AccountService client provides functionality for retrieving reporting data from Searchlight accounts, while retaining all the functionality found in the SearchlightService client. A Searchlight account id is required upon instantiation.\n```\nfrom searchlight_api import client\n# instantiate the AccountService client\naccount_service = client.AccountService(YYYY)\n# retrieve all web properties tracked in the account\nweb_properties = account_service.get_web_properties()\n\nweb_property_id = web_properties[0]['webPropertyId']\n\n# the web_property_id can be used to get the name of the corresponding domain\ndomain_name = account_service.get_domain_name(web_property_id)\n\n# use the web_property_id to get all tracked searches in the account\ntracked_searches = account_service.get_tracked_searches(web_property_id)\n\n# get a rank_source_id that the web_property is tracked against\nrank_source_id = web_properties[0]['rankSourceInfo'][0]['rankSourceId']\n\n# retrieve rank data for searches tracked against a web property and rank source for a given date within a reporting interval.\n# by default the current date is used.\nranks = account_service.get_ranks(web_property_id, rank_source_id, date='2019-01-12')\n\n# retrieve search volume data for searches tracked against a web property and rank source for a given date within a reporting interval.\n# by default the current date is used.\nsearch_volume = account_service.get_volume(web_property_id, rank_source_id, date='2019-01-12')\n```\n\n##### Analysis\nAnalysis allows you to use the AccountService client to aggregate reporting data across an entire account for a given date.\n\n```\nfrom searchlight_api.client import AccountService\nfrom searchlight_api import analysis\n\naccount_service = AccountService(YYYY)\n\nrank_data = analysis.rank_data(account_service, date='2019-01-12')\nsearch_volume = analysis.search_volume(account_service)\n```\n\nTo request additional aggregation methods, reach out to dgoodman@conductor.com or pmurphy@conductor.com\n\n##### Using Pandas with Searchlight API Client\n\n```\nfrom searchlight_api import client, analysis\nimport pandas as pd\n\n# instantiate AccountService object\naccount_service = client.AccountService(YYYY)\n\n# get rank sources, locations and devices and turn to dfs\nrank_source_df = pd.DataFrame(account_service.get_rank_sources())\nlocation_df = pd.DataFrame(account_service.get_locations())\ndevice_df = pd.DataFrame(account_service.get_devices())\n\n# get the tracked searches and turn into a df\ntracked_search_df = pd.DataFrame(analysis.all_tracked_searches(account_service))\n\n# turn search_volume and rank_data to Data Frames\nsearch_volume_df = pd.DataFrame(analysis.search_volume(account_service))\nrank_data_df = pd.DataFrame(analysis.rank_data(account_service))\n\nreport = pd.merge(rank_data_df, search_volume_df, on=['trackedSearchId', 'rankSourceId', 'webPropertyId'])\nreport = report.merge(rank_source_df, on='rankSourceId', how='left')\nprint(report.head())\n itemType rankSourceId standardRank target targetDomainName \\\n0 ANSWER_BOX 1 3.0 example.com\n1 IMAGE_RESULT 1 NaN example.com\n2 LOCAL_RESULT 1 NaN www.organiccompetitor.com\n3 LOCAL_RESULT 1 NaN www.organiccompetitor.com\n4 LOCAL_RESULT 1 NaN www.organiccompetitor.com\n targetUrl targetWebPropetyId \\\n0 https://www.example.com/subfolder1/ 43162.0\n1 https://www.example.com/subfolder2/... 43162.0\n2 http://www.organiccompetitor.com/subfolder... NaN\n3 http://www.organiccompetitor.com/subfolder/... NaN\n4 http://www.organiccompetitor.com/subfolder/... NaN\n trackedSearchId trueRank webPropertyId averageVolume \\\n0 7188291 6 43162 135000\n1 7188291 62 43162 135000\n2 7188291 4 43162 135000\n3 7188291 2 43162 135000\n4 7188291 3 43162 135000\n volumeItems baseDomain \\\n0 [{'volume': 165000, 'month': 11, 'year': 2018}... google.com\n1 [{'volume': 165000, 'month': 11, 'year': 2018}... google.com\n2 [{'volume': 165000, 'month': 11, 'year': 2018}... google.com\n3 [{'volume': 165000, 'month': 11, 'year': 2018}... google.com\n4 [{'volume': 165000, 'month': 11, 'year': 2018}... google.com\n description name deviceId isActive locationId \\\n0 Google (US / English) GOOGLE_EN_US 1 True 1\n1 Google (US / English) GOOGLE_EN_US 1 True 1\n2 Google (US / English) GOOGLE_EN_US 1 True 1\n3 Google (US / English) GOOGLE_EN_US 1 True 1\n4 Google (US / English) GOOGLE_EN_US 1 True 1\n preferredUrl queryPhrase\n0 http://www.example.com/ example phrase\n1 http://www.example.com/ example phrase\n2 http://www.example.com/ example phrase\n3 http://www.example.com/ example phrase\n4 http://www.example.com/ example phrase\n```", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/Conductor/searchlight-api-client-python", "keywords": "", "license": "LICENSE", "maintainer": "", "maintainer_email": "", "name": "searchlight-api", "package_url": "https://pypi.org/project/searchlight-api/", "platform": "", "project_url": "https://pypi.org/project/searchlight-api/", "project_urls": { "Homepage": "https://github.com/Conductor/searchlight-api-client-python" }, "release_url": "https://pypi.org/project/searchlight-api/1.0.0/", "requires_dist": null, "requires_python": "", "summary": "A client to assist in connecting with the Conductor Searchlight API", "version": "1.0.0" }, "last_serial": 5283558, "releases": { "0.0.1": [ { "comment_text": "", "digests": { "md5": "1bc623d0239298f4c49de637cce78ac7", "sha256": "c0c718bca61c6d0353580dfdc80022499cb57984dba5db5a401066956077ded8" }, "downloads": -1, "filename": "searchlight_api-0.0.1.tar.gz", "has_sig": false, "md5_digest": "1bc623d0239298f4c49de637cce78ac7", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9413, "upload_time": "2019-02-11T16:30:46", "url": "https://files.pythonhosted.org/packages/16/bf/875a82b9d457475a909bdcbc59de71335c12c527df92935c79c23e30e467/searchlight_api-0.0.1.tar.gz" } ], "1.0.0": [ { "comment_text": "", "digests": { "md5": "7db66c346d5b3477146d58c7b590a19f", "sha256": "ff1e80bf439f3ba7d10b457eda54c0cea8c9405e2a1ab477603eb1978b25475f" }, "downloads": -1, "filename": "searchlight_api-1.0.0.tar.gz", "has_sig": false, "md5_digest": "7db66c346d5b3477146d58c7b590a19f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 11545, "upload_time": "2019-05-17T18:42:17", "url": "https://files.pythonhosted.org/packages/b3/d8/c92236088e0e1df2caeebe080792a1b812de2f07a81b4a407bd04b8aa647/searchlight_api-1.0.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "7db66c346d5b3477146d58c7b590a19f", "sha256": "ff1e80bf439f3ba7d10b457eda54c0cea8c9405e2a1ab477603eb1978b25475f" }, "downloads": -1, "filename": "searchlight_api-1.0.0.tar.gz", "has_sig": false, "md5_digest": "7db66c346d5b3477146d58c7b590a19f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 11545, "upload_time": "2019-05-17T18:42:17", "url": "https://files.pythonhosted.org/packages/b3/d8/c92236088e0e1df2caeebe080792a1b812de2f07a81b4a407bd04b8aa647/searchlight_api-1.0.0.tar.gz" } ] }