Elastic Site Search API Client for Python
Project description
A first-party Python client for the Elastic Site Search API.
Contents
Getting started 🐣
You can install the latest version of the Elastic Site Search client using pip
:
pip install elastic-site-search
To install locally, clone this repository, cd
into the directory and run:
python setup.py install
Note: This client has been developed for the Elastic Site Search API endpoints only. You may refer to the Elastic Site Search API Documentation for additional context.
Usage
-
Create Elastic Site Search account and get your API key from your Account Settings.
-
Configure your client:
from elastic_site_search import Client
client = Client(api_key='YOUR_API_KEY')
- Create an
Engine
named e.g.youtube
:
engine = client.create_engine('youtube')
- Create your
DocumentType
s:
client.create_document_type('youtube', 'videos');
client.create_document_type('youtube', 'channels');
Indexing
Now 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.
Add a Document
to the videos
DocumentType
:
client.create_document('youtube', 'videos', {
'external_id': 'external_id1',
'fields': [
{'name': 'title', 'value': 'Site Search Demo', 'type': 'string'},
{'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search'], 'type': 'string'},
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=pITuOcGgpBs', 'type': 'enum'},
{'name': 'category', 'value': ['Tutorial', 'Product'], 'type': 'enum'},
{'name': 'publication_date', 'value': '2012-05-08T12:07Z', 'type': 'date'},
{'name': 'likes', 'value': 31, 'type': 'integer'},
{'name': 'length', 'value': 1.50, 'type': 'float'}
]
})
Add a Document
to the channels
DocumentType
:
client.create_document('youtube', 'channels', {
'external_id': 'external_id1',
'fields': [
{'name': 'title', 'value': 'Elastic', 'type': 'string'},
{'name': 'url', 'value': 'http://www.youtube.com/user/elasticsearch', 'type': 'enum'},
{'name': 'video_views', 'value': 15678, 'type': 'integer'},
{'name': 'video_counts', 'value': 6, 'type': 'integer'}
]
})
Searching
Now 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:
video_results = client.search_document_type('youtube', 'videos', 'site search')
channel_results = client.search_document_type('youtube', 'channels', 'site search')
or search all DocumentType
s on your Engine
at once:
results = client.search('youtube', 'site search')
Autocomplete
Finally, as with full-text searches, you may perform autocomplete-style (prefix match) searches as well:
results = client.suggest('youtube', 'sit')
or
results = client.suggest_document_type('youtube', 'videos', 'sit')
API Documentation
Configuration:
Before issuing commands to the API, configure the client with your API key:
from elastic_site_search import Client
client = Client(api_key='YOUR_API_KEY')
You can find your API key in your Account Settings.
Search
If you want to search for e.g. site search
on your Engine
, you can use:
results = client.search('youtube', 'site search')
To limit the search to only the videos
DocumentType:
results = client.search_document_type('youtube', 'videos', 'site search')
Both 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. Here is an example for showing only videos
that are in the category
Tutorial
:
results = client.search_document_type('youtube', 'videos', 'site search', {'filters': {'videos': {'category': 'Tutorial'}}})
Autocomplete
Autocompletes have the same functionality as searches. You can autocomplete using all documents:
results = client.suggest('youtube', 'sit')
or just for one DocumentType:
results = client.suggest_document_type('youtube', 'videos', 'sit')
or add options to have more control over the results:
results = client.suggest('youtube', 'sit', {'sort_field': {'videos': 'likes'}})
Engines
Retrieve every Engine
:
engines = client.engines
Create a new Engine
with the name youtube
:
engine = client.create_engine('youtube')
Retrieve an Engine
by slug
or id
:
engine = client.engine('youtube')
To delete an Engine
you need the slug
or the id
field of an engine
:
client.destroy_engine('youtube')
Document Types
Retrieve DocumentTypes
s of the Engine
with the slug
field youtube
:
document_types = client.document_types('youtube')
Show the second batch of documents:
document_types = client.document_types('youtube', 2)
Create a new DocumentType
for an Engine
with the name videos
:
document_type = client.create_document_type('youtube', 'videos')
Retrieve an DocumentType
by slug
or id
:
document_type = client.document_type('youtube', 'videos')
Delete a DocumentType
using the slug
or id
of it:
client.destroy_document_type('youtube', 'videos')
Documents
Retrieve all Document
s of Engine
youtube
and DocumentType
videos
:
documents = client.documents('youtube', 'videos')
Retrieve a specific Document
using its id
or external_id
:
document = client.document('youtube', 'videos', 'external_id1')
Create a new Document
with mandatory external_id
and user-defined fields:
document = client.create_document('youtube', 'videos', {
'external_id': 'external_id1',
'fields': [
{'name': 'title', 'value': 'Site Search Demo', 'type': 'string'},
{'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search'], 'type': 'string'},
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=pITuOcGgpBs', 'type': 'enum'},
{'name': 'category', 'value': ['Tutorial', 'Product'], 'type': 'enum'},
{'name': 'publication_date', 'value': '2012-05-08T12:07Z', 'type': 'date'},
{'name': 'likes', 'value': 31, 'type': 'integer'},
{'name': 'length', 'value': 1.50, 'type': 'float'}
]
})
Create multiple Document
s at once and return status for each Document
creation:
stati = client.create_documents('youtube', 'videos',
{
'external_id': 'external_id1',
'fields': [
{'name': 'title', 'value': 'Site Search Demo', 'type': 'string'},
{'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search'], 'type': 'string'},
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=pITuOcGgpBs', 'type': 'enum'},
{'name': 'category', 'value': ['Tutorial', 'Product'], 'type': 'enum'},
{'name': 'publication_date', 'value': '2012-05-08T12:07Z', 'type': 'date'},
{'name': 'likes', 'value': 27, 'type': 'integer'},
{'name': 'length', 'value': 1.50, 'type': 'float'}
]
},
{
'external_id': 'external_id2',
'fields': [
{'name': 'title', 'value': 'Site Search Search Wordpress Plugin Demo', 'type': 'string'},
{'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search', 'WordPress'], 'type': 'string'},
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=rukXYKEpvS4', 'type': 'enum'},
{'name': 'category', 'value': ['Tutorial', 'Wordpress'], 'type': 'enum'},
{'name': 'publication_date', 'value': '2012-08-15T09:07Z', 'type': 'date'},
{'name': 'likes', 'value': 2, 'type': 'integer'},
{'name': 'length', 'value': 2.16, 'type': 'float'}
]
}
)
Update fields of an existing Document
specified by id
or external_id
:
client.update_document('youtube','videos','external_id1', {'likes': 28, 'category': ['Tutorial', 'Search']})
Update multiple Document
s at once:
stati = client.update_documents('youtube', 'videos', [
{'external_id': '2', 'fields': {'likes': 29}},
{'external_id': '3', 'fields': {'likes': 4}}
])
Create or update a Document
:
document = client.create_or_update_document('youtube', 'videos', {
'external_id': 'external_id3',
'fields': [
{'name': 'title', 'value': 'Site Search Install Type 1: Show results in an overlay', 'type': 'string'},
{'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search', 'Web'], 'type': 'string'},
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=mj2ApIx3frs', 'type': 'enum'}
]
})
Create or update multiple Documents
at once:
stati = client.create_or_update_documents('youtube', 'videos',
{
'external_id': 'external_id4',
'fields': [
{'name': 'title', 'value': 'Site Search Install Type 2: Show results on the current page', 'type': 'string'},
{'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search', 'Web'], 'type': 'string'},
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=6uaZXYK2WOE', 'type': 'enum'}
]
},
{
'external_id': 'external_id5',
'fields': [
{'name': 'title', 'value': 'Site Search Install Type 3: Show results on a new page', 'type': 'string'},
{'name': 'tags', 'value': ['Site Search', 'Search', 'Full text search', 'Web'], 'type': 'string'},
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=ebSWAscBPtc', 'type': 'enum'}
]
}
)
Destroy a Document
:
client.destroy_document('youtube','videos','external_id5')
Destroy multiple Document
s at once:
stati = client.destroy_documents('youtube','videos',['external_id2','external_id3','external_id6'])
Domains
Retrieve all Domain
s of Engine
websites
:
domains = client.domains('websites')
Retrieve a specific Domain
by id
:
domain = client.domain('websites', 'generated_id')
Create a new Domain
with the URL https://elastic.co
and start crawling:
domain = client.create_domain('websites', 'https://elastic.co')
Delete a Domain
using its id
:
client.destroy_domain('websites', 'generated_id')
Initiate a recrawl of a specific Domain
using its id
:
client.recrawl_domain('websites', 'generated_id')
Add or update a URL for a Domain
:
client.crawl_url('websites', 'generated_id', 'https://elastic.co/new/path/about.html')
Analytics
To get the amount of searches on your Engine
in the last 14 days use:
searches = client.analytics_searches('youtube')
You can also use a specific start and/or end date:
searches = client.analytics_searches('youtube', '2013-01-01', '2013-02-01')
To get the amount of autoselects (clicks on autocomplete results) use:
autoselects = client.analytics_autoselects('youtube')
As with searches you can also limit by start and/or end date:
autoselects = client.analytics_autoselects('youtube', 2, 10)
If you are interested in the top queries for your Engine
you can use:
top_queries = client.analytics_top_queries('youtube')
To see more top queries you can paginate through them using:
top_queries = client.analytics_top_queries('youtube', page=2)
Or you can get the top queries in a specific date range:
top_queries = client.analytics_top_queries_in_range('youtube', '2013-01-01', '2013-02-01')
If 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:
top_no_result_queries = client.analytics_top_no_result_queries('youtube')
You can also specify a date range for no result queries:
top_no_result_queries = client.analytics_top_no_result_queries('youtube', '2013-01-01', '2013-02-01')
Running Tests
pip install -r test_requirements.txt
python tests/test_client.py
FAQ 🔮
Where do I report issues with the client?
If something is not working as expected, please open an issue.
Where can I learn more about Site Search?
Your best bet is to read the documentation.
Where else can I go to get help?
You can checkout the Elastic Site Search community discuss forums.
Contribute 🚀
We welcome contributors to the project. Before you begin, a couple notes...
- Before opening a pull request, please create an issue to discuss the scope of your proposal.
- Please write simple code and concise documentation, when appropriate.
License 📗
Thank you to all the contributors!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for elastic-site-search-2.1.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2be60fbb924ab79d334aebf291112648fe85e4971ecfe36d07622148a4b3ac75 |
|
MD5 | 7ab9411139ae4c61c46c411104802a6b |
|
BLAKE2b-256 | 1d7331d5a2df893fac75b0fbb366ea35c5972a08043793f86db350a26d4f6b31 |
Hashes for elastic_site_search-2.1.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fccd6e72aa73a192685650a26fe9b6ff9dbc618f8a10faba905205bcc2c8dc1d |
|
MD5 | 2e400229bffb3aa2d03c5f3b5813b1d8 |
|
BLAKE2b-256 | 57087e91d37506d3580725edcf3f3befcba1ec16c9b5bae4a06b2881205674b2 |