{
"info": {
"author": "Elastic",
"author_email": "support@elastic.co",
"bugtrack_url": null,
"classifiers": [
"Intended Audience :: Developers",
"License :: OSI Approved :: Apache Software License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 2",
"Programming Language :: Python :: 2.7",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.3",
"Programming Language :: Python :: 3.4",
"Programming Language :: Python :: 3.5",
"Programming Language :: Python :: 3.6",
"Topic :: Software Development :: Libraries :: Python Modules"
],
"description": "![\"Elastic](\"https://github.com/elastic/site-search-python/blob/master/logo-site-search.png?raw=true\")
\n\n![\"CircleCI](\"https://img.shields.io/circleci/build/github/elastic/site-search-python/master\")
\n![\"GitHub](\"https://img.shields.io/github/release/elastic/site-search-python/all.svg?style=flat-square\")
\n\n> A first-party Python client for the [Elastic Site Search API](https://elastic.co/products/site-search).\n\n## Contents\n\n+ [Getting started](#getting-started-)\n+ [Usage](#usage)\n+ [Running tests](#running-tests)\n+ [FAQ](#faq-)\n+ [Contribute](#contribute-)\n+ [License](#license-)\n\n***\n\n## Getting started \ud83d\udc23\n\nYou can install the latest version of the Elastic Site Search client using `pip`:\n\n ```bash\n pip install elastic-site-search\n ```\n\nTo install locally, clone this repository, `cd` into the directory and run:\n\n ```bash\n python setup.py install\n ```\n\n> **Note:** This client has been developed for the [Elastic Site Search](https://elastic.co/products/site-search) API endpoints only. You may refer to the [Elastic Site Search API Documentation](https://swiftype.com/documentation/site-search/overview) for additional context.\n\n## Usage\n\n1. Create [Elastic Site Search account](https://app.swiftype.com/signup) and get your API key from your [Account Settings](https://app.swiftype.com/settings/account).\n\n2. Configure your client:\n\n ```python\n from elastic_site_search import Client\n client = Client(api_key='YOUR_API_KEY')\n ```\n\n3. Create an `Engine` named e.g. `youtube`:\n\n ```python\n engine = client.create_engine('youtube')\n ```\n\n4. Create your `DocumentType`s:\n\n ```python\n client.create_document_type('youtube', 'videos');\n client.create_document_type('youtube', 'channels');\n ```\n\n### Indexing\n\nNow you need to create your `Document`s. It's very important to think about the type of each field you create a `Document`. The `DocumentType` the `Document` belongs to will remember each fields type and it is not possible to change it. The type specifies a fields features and you should choose them wisely. For details please have a look at our [Field Types Documentation](https://swiftype.com/documentation/overview#field_types).\n\nAdd a `Document` to the `videos` `DocumentType`:\n\n ```python\n client.create_document('youtube', 'videos', {\n 'external_id': 'external_id1',\n 'fields': [\n {'name': 'title', 'value': 'Site Search Demo', 'type': 'string'},\n {'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search'], 'type': 'string'},\n {'name': 'url', 'value': 'http://www.youtube.com/watch?v=pITuOcGgpBs', 'type': 'enum'},\n {'name': 'category', 'value': ['Tutorial', 'Product'], 'type': 'enum'},\n {'name': 'publication_date', 'value': '2012-05-08T12:07Z', 'type': 'date'},\n {'name': 'likes', 'value': 31, 'type': 'integer'},\n {'name': 'length', 'value': 1.50, 'type': 'float'}\n ]\n })\n ```\n\nAdd a `Document` to the `channels` `DocumentType`:\n\n ```python\n client.create_document('youtube', 'channels', {\n 'external_id': 'external_id1',\n 'fields': [\n {'name': 'title', 'value': 'Elastic', 'type': 'string'},\n {'name': 'url', 'value': 'http://www.youtube.com/user/elasticsearch', 'type': 'enum'},\n {'name': 'video_views', 'value': 15678, 'type': 'integer'},\n {'name': 'video_counts', 'value': 6, 'type': 'integer'}\n ]\n })\n ```\n\n### Searching\n\nNow your `Engine` is ready to receive queries. By default, search queries will match any fields that are of type `string` or `text`. You can search each `DocumentType` individually:\n\n ```python\n video_results = client.search_document_type('youtube', 'videos', 'site search')\n channel_results = client.search_document_type('youtube', 'channels', 'site search')\n ```\n\nor search all `DocumentType`s on your `Engine` at once:\n\n ```python \n results = client.search('youtube', 'site search')\n ```\n\n### Autocomplete\n\nFinally, as with full-text searches, you may perform autocomplete-style (prefix match) searches as well:\n\n ```python\n results = client.suggest('youtube', 'sit')\n ```\n\nor\n\n ```python\n results = client.suggest_document_type('youtube', 'videos', 'sit')\n ```\n\n## API Documentation\n\n### Configuration:\n\nBefore issuing commands to the API, configure the client with your API key:\n\n ```python\n from elastic_site_search import Client\n client = Client(api_key='YOUR_API_KEY')\n ```\n\nYou can find your API key in your [Account Settings](https://swiftype.com/user/edit).\n\n### Search\n\nIf you want to search for e.g. `site search` on your `Engine`, you can use:\n\n ```python\n results = client.search('youtube', 'site search')\n ```\n\nTo limit the search to only the `videos` DocumentType:\n\n ```python\n results = client.search_document_type('youtube', 'videos', 'site search')\n ```\n\nBoth search methods allow you to specify options as an extra parameter to e.g. filter or sort on fields. For more details on these options please have a look at the [Search Options](https://swiftype.com/documentation/searching). Here is an example for showing only `videos` that are in the `category` `Tutorial`:\n\n ```python\n results = client.search_document_type('youtube', 'videos', 'site search', {'filters': {'videos': {'category': 'Tutorial'}}})\n ```\n\n### Autocomplete\n\nAutocompletes have the same functionality as searches. You can autocomplete using all documents:\n\n ```python\n results = client.suggest('youtube', 'sit')\n ```\n\nor just for one DocumentType:\n\n ```python\n results = client.suggest_document_type('youtube', 'videos', 'sit')\n ```\n\nor add options to have more control over the results:\n\n ```python\n results = client.suggest('youtube', 'sit', {'sort_field': {'videos': 'likes'}})\n ```\n\n### Engines\n\nRetrieve every `Engine`:\n\n ```python\n engines = client.engines\n ```\n\nCreate a new `Engine` with the name `youtube`:\n\n ```python\n engine = client.create_engine('youtube')\n ```\n\nRetrieve an `Engine` by `slug` or `id`:\n\n ```python\n engine = client.engine('youtube')\n ```\n\nTo delete an `Engine` you need the `slug` or the `id` field of an `engine`:\n\n ```python\n client.destroy_engine('youtube')\n ```\n\n### Document Types\n\nRetrieve `DocumentTypes`s of the `Engine` with the `slug` field `youtube`:\n\n ```python\n document_types = client.document_types('youtube')\n ```\n\nShow the second batch of documents:\n\n ```python\n document_types = client.document_types('youtube', 2)\n ```\n\nCreate a new `DocumentType` for an `Engine` with the name `videos`:\n\n ```python\n document_type = client.create_document_type('youtube', 'videos')\n ```\n\nRetrieve an `DocumentType` by `slug` or `id`:\n\n ```python\n document_type = client.document_type('youtube', 'videos')\n ```\n\nDelete a `DocumentType` using the `slug` or `id` of it:\n\n ```python\n client.destroy_document_type('youtube', 'videos')\n ```\n\n### Documents\n\nRetrieve all `Document`s of `Engine` `youtube` and `DocumentType` `videos`:\n\n ```python\n documents = client.documents('youtube', 'videos')\n ```\n\nRetrieve a specific `Document` using its `id` or `external_id`:\n\n ```python\n document = client.document('youtube', 'videos', 'external_id1')\n ```\n\nCreate a new `Document` with mandatory `external_id` and user-defined fields:\n\n ```python\n document = client.create_document('youtube', 'videos', {\n 'external_id': 'external_id1',\n 'fields': [\n {'name': 'title', 'value': 'Site Search Demo', 'type': 'string'},\n {'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search'], 'type': 'string'},\n {'name': 'url', 'value': 'http://www.youtube.com/watch?v=pITuOcGgpBs', 'type': 'enum'},\n {'name': 'category', 'value': ['Tutorial', 'Product'], 'type': 'enum'},\n {'name': 'publication_date', 'value': '2012-05-08T12:07Z', 'type': 'date'},\n {'name': 'likes', 'value': 31, 'type': 'integer'},\n {'name': 'length', 'value': 1.50, 'type': 'float'}\n ]\n })\n ```\n\nCreate multiple `Document`s at once and return status for each `Document` creation:\n\n ```python\n stati = client.create_documents('youtube', 'videos',\n {\n 'external_id': 'external_id1',\n 'fields': [\n {'name': 'title', 'value': 'Site Search Demo', 'type': 'string'},\n {'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search'], 'type': 'string'},\n {'name': 'url', 'value': 'http://www.youtube.com/watch?v=pITuOcGgpBs', 'type': 'enum'},\n {'name': 'category', 'value': ['Tutorial', 'Product'], 'type': 'enum'},\n {'name': 'publication_date', 'value': '2012-05-08T12:07Z', 'type': 'date'},\n {'name': 'likes', 'value': 27, 'type': 'integer'},\n {'name': 'length', 'value': 1.50, 'type': 'float'}\n ]\n }, \n {\n 'external_id': 'external_id2',\n 'fields': [\n {'name': 'title', 'value': 'Site Search Search Wordpress Plugin Demo', 'type': 'string'},\n {'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search', 'WordPress'], 'type': 'string'},\n {'name': 'url', 'value': 'http://www.youtube.com/watch?v=rukXYKEpvS4', 'type': 'enum'},\n {'name': 'category', 'value': ['Tutorial', 'Wordpress'], 'type': 'enum'},\n {'name': 'publication_date', 'value': '2012-08-15T09:07Z', 'type': 'date'},\n {'name': 'likes', 'value': 2, 'type': 'integer'},\n {'name': 'length', 'value': 2.16, 'type': 'float'}\n ]\n }\n )\n ```\n\nUpdate fields of an existing `Document` specified by `id` or `external_id`:\n\n ```python\n client.update_document('youtube','videos','external_id1', {'likes': 28, 'category': ['Tutorial', 'Search']})\n ```\n\nUpdate multiple `Document`s at once:\n\n ```python\n stati = client.update_documents('youtube', 'videos', [\n {'external_id': '2', 'fields': {'likes': 29}},\n {'external_id': '3', 'fields': {'likes': 4}}\n ])\n ```\n\nCreate or update a `Document`:\n\n ```python\n document = client.create_or_update_document('youtube', 'videos', {\n 'external_id': 'external_id3',\n 'fields': [\n {'name': 'title', 'value': 'Site Search Install Type 1: Show results in an overlay', 'type': 'string'},\n {'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search', 'Web'], 'type': 'string'},\n {'name': 'url', 'value': 'http://www.youtube.com/watch?v=mj2ApIx3frs', 'type': 'enum'}\n ]\n })\n ```\n\nCreate or update multiple `Documents` at once:\n\n ```python\n stati = client.create_or_update_documents('youtube', 'videos',\n {\n 'external_id': 'external_id4',\n 'fields': [\n {'name': 'title', 'value': 'Site Search Install Type 2: Show results on the current page', 'type': 'string'},\n {'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search', 'Web'], 'type': 'string'},\n {'name': 'url', 'value': 'http://www.youtube.com/watch?v=6uaZXYK2WOE', 'type': 'enum'}\n ]\n },\n {\n 'external_id': 'external_id5',\n 'fields': [\n {'name': 'title', 'value': 'Site Search Install Type 3: Show results on a new page', 'type': 'string'},\n {'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search', 'Web'], 'type': 'string'},\n {'name': 'url', 'value': 'http://www.youtube.com/watch?v=ebSWAscBPtc', 'type': 'enum'}\n ]\n }\n )\n ```\n\nDestroy a `Document`:\n ```python\n client.destroy_document('youtube','videos','external_id5')\n ```\n\nDestroy multiple `Document`s at once:\n\n ```python\n stati = client.destroy_documents('youtube','videos',['external_id2','external_id3','external_id6'])\n ```\n\n### Domains\n\nRetrieve all `Domain`s of `Engine` `websites`:\n\n ```python\n domains = client.domains('websites')\n ```\n\nRetrieve a specific `Domain` by `id`:\n\n ```python\n domain = client.domain('websites', 'generated_id')\n ```\n\nCreate a new `Domain` with the URL `https://elastic.co` and start crawling:\n\n ```python\n domain = client.create_domain('websites', 'https://elastic.co')\n ```\n\nDelete a `Domain` using its `id`:\n\n ```python\n client.destroy_domain('websites', 'generated_id')\n ```\n\nInitiate a recrawl of a specific `Domain` using its `id`:\n\n ```python\n client.recrawl_domain('websites', 'generated_id')\n ```\n\nAdd or update a URL for a `Domain`:\n\n ```python\n client.crawl_url('websites', 'generated_id', 'https://elastic.co/new/path/about.html')\n ```\n\n### Analytics\n\nTo get the amount of searches on your `Engine` in the last 14 days use:\n\n ```python\n searches = client.analytics_searches('youtube')\n ```\n\nYou can also use a specific start and/or end date:\n\n ```python\n searches = client.analytics_searches('youtube', '2013-01-01', '2013-02-01')\n ```\n\nTo get the amount of autoselects (clicks on autocomplete results) use:\n\n ```python\n autoselects = client.analytics_autoselects('youtube')\n ```\n\nAs with searches you can also limit by start and/or end date:\n\n ```python\n autoselects = client.analytics_autoselects('youtube', 2, 10)\n ```\n\nIf you are interested in the top queries for your `Engine` you can use:\n\n ```python\n top_queries = client.analytics_top_queries('youtube')\n ```\n\nTo see more top queries you can paginate through them using:\n ```python\n top_queries = client.analytics_top_queries('youtube', page=2)\n ```\n\nOr you can get the top queries in a specific date range:\n\n ```python\n top_queries = client.analytics_top_queries_in_range('youtube', '2013-01-01', '2013-02-01')\n ```\n\nIf you want to improve you search results, you should always have a look at search queries, that return no results and perhaps add some Documents that match for this query or use our pining feature to add Documents for this query:\n\n ```python\n top_no_result_queries = client.analytics_top_no_result_queries('youtube')\n ```\n\nYou can also specify a date range for no result queries:\n\n ```python\n top_no_result_queries = client.analytics_top_no_result_queries('youtube', '2013-01-01', '2013-02-01')\n ```\n## Running Tests\n\n ```bash\n pip install -r test_requirements.txt\n python tests/test_client.py\n ```\n\n## FAQ \ud83d\udd2e\n\n### Where do I report issues with the client?\n\nIf something is not working as expected, please open an [issue](https://github.com/elastic/site-search-python/issues/new).\n\n### Where can I learn more about Site Search?\n\nYour best bet is to read the [documentation](https://swiftype.com/documentation/site-search).\n\n### Where else can I go to get help?\n\nYou can checkout the [Elastic Site Search community discuss forums](https://discuss.elastic.co/c/site-search).\n\n## Contribute \ud83d\ude80\n\nWe welcome contributors to the project. Before you begin, a couple notes...\n\n+ Before opening a pull request, please create an issue to [discuss the scope of your proposal](https://github.com/elastic/site-search-python/issues).\n+ Please write simple code and concise documentation, when appropriate.\n\n## License \ud83d\udcd7\n\n[Apache 2.0](https://github.com/elastic/site-search-python/blob/master/LICENSE) \u00a9 [Elastic](https://github.com/elastic)\n\nThank you to all the [contributors](https://github.com/elastic/site-search-python/graphs/contributors)!",
"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/elastic/site-search-python",
"keywords": "",
"license": "Apache 2.0",
"maintainer": "",
"maintainer_email": "",
"name": "elastic-site-search",
"package_url": "https://pypi.org/project/elastic-site-search/",
"platform": "",
"project_url": "https://pypi.org/project/elastic-site-search/",
"project_urls": {
"Homepage": "https://github.com/elastic/site-search-python"
},
"release_url": "https://pypi.org/project/elastic-site-search/2.0.1/",
"requires_dist": null,
"requires_python": "",
"summary": "Elastic Site Search API Client for Python",
"version": "2.0.1",
"yanked": false,
"yanked_reason": null
},
"last_serial": 6019988,
"releases": {
"2.0.0": [
{
"comment_text": "",
"digests": {
"md5": "d1133bc38c5fe03d91ab53128c966d67",
"sha256": "f63da014d4de0fe34ecbab25a33ff7fbda598f08551cfc49ce40c57778827167"
},
"downloads": -1,
"filename": "elastic-site-search-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "d1133bc38c5fe03d91ab53128c966d67",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12047,
"upload_time": "2019-08-09T05:05:22",
"upload_time_iso_8601": "2019-08-09T05:05:22.223682Z",
"url": "https://files.pythonhosted.org/packages/66/8c/c5c352a66542f508d78b2935a0ba30d4a1db8a1d3e5c5d364a78e6cd0936/elastic-site-search-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"2.0.1": [
{
"comment_text": "",
"digests": {
"md5": "e0d529b89df10bedb00c6166900dfe7a",
"sha256": "86f94c3b6796cd87edbd4cc9100baae408e4f99b24f80c9c9455c75e946d24c1"
},
"downloads": -1,
"filename": "elastic-site-search-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "e0d529b89df10bedb00c6166900dfe7a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12169,
"upload_time": "2019-09-16T20:42:11",
"upload_time_iso_8601": "2019-09-16T20:42:11.937611Z",
"url": "https://files.pythonhosted.org/packages/71/54/cf90228358006820fe7e803c15e8d8136940907373253e96c4067b62ade2/elastic-site-search-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "e0d529b89df10bedb00c6166900dfe7a",
"sha256": "86f94c3b6796cd87edbd4cc9100baae408e4f99b24f80c9c9455c75e946d24c1"
},
"downloads": -1,
"filename": "elastic-site-search-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "e0d529b89df10bedb00c6166900dfe7a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12169,
"upload_time": "2019-09-16T20:42:11",
"upload_time_iso_8601": "2019-09-16T20:42:11.937611Z",
"url": "https://files.pythonhosted.org/packages/71/54/cf90228358006820fe7e803c15e8d8136940907373253e96c4067b62ade2/elastic-site-search-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"vulnerabilities": []
}