Skip to content

Commit c3a277c

Browse files
author
Tobias Hauth
committed
fill readme
1 parent fe4285c commit c3a277c

File tree

1 file changed

+220
-0
lines changed

1 file changed

+220
-0
lines changed

‎README.md

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,224 @@
11
Swiftype API Client for Python
22
===============================
33

4+
# Configuration:
45

6+
Before issuing commands to the API, configure the client with your API key:
7+
8+
import swiftype
9+
client = swiftype.Client(api_key='YOUR_API_KEY')
10+
11+
You can find your API key in your [Account Settings](https://swiftype.com/user/edit).
12+
13+
# Search
14+
15+
If you want to search for e.g. `action` on your engine, you can use:
16+
17+
results = client.search('bookstore', 'action')
18+
19+
To limit the search to only the `books` DocumentType:
20+
21+
results = client.search_document_type('bookstore', 'books', 'action')
22+
23+
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 pelease have a look at the [Search Options](https://swiftype.com/documentation/searching). Here is an example for showing only books that are in stock:
24+
25+
results = client.search_document_type('bookstore', 'books', 'action', {'filters': {'books': {'in_stock': true}}})
26+
27+
# Autocomplete
28+
29+
Autocompletes have the same functionality as searches. You can autocomplete using all documents:
30+
31+
results = client.suggest('bookstore', 'acti')
32+
33+
or just for one DocumentType:
34+
35+
results = client.suggest_document_type('bookstore', 'books', 'acti')
36+
37+
or add options to have more control over the results:
38+
39+
results = client.suggest('bookstore', 'acti', {'sort_field': {'books': 'price'}})
40+
41+
# Engines
42+
43+
Retrieve every `Engine`:
44+
45+
engines = client.engines
46+
47+
Create a new `Engine` with the name `bookstore`:
48+
49+
engine = client.create_engine('bookstore')
50+
51+
Retrieve an `Engine` by `slug` or `id`:
52+
53+
engine = client.engine('bookstore')
54+
55+
To delete an `Engine` you need the `slug` or the `id` field of an `engine`:
56+
57+
client.destroy_engine('bookstore')
58+
59+
# Document Types
60+
61+
Retrieve `DocumentTypes`s of the `Engine` with the `slug` field `bookstore`:
62+
63+
document_types = client.document_types('bookstore')
64+
65+
Show the second batch of documents:
66+
67+
document_types = client.document_types('bookstore', 2)
68+
69+
Create a new `DocumentType` for an `Engine` with the name `books`:
70+
71+
document_type = client.create_document_type('bookstore', 'books')
72+
73+
Retrieve an `DocumentType` by `slug` or `id`:
74+
75+
document_type = client.document_type('bookstore', 'books')
76+
77+
Delete a `DocumentType` using the `slug` or `id` of it:
78+
79+
client.destroy_document_type('bookstore', 'books')
80+
81+
# Documents
82+
83+
Retrieve all `Document`s of `Engine` `bookstore` and `DocumentType` `books`:
84+
85+
documents = client.documents('bookstore', 'books')
86+
87+
Retrieve a specific `Document` using its `id` or `external_id`:
88+
89+
document = client.document('bookstore', 'books', 'id1')
90+
91+
Create a new `Document` with mandatory `external_id` and user-defined fields:
92+
93+
document = client.create_document('bookstore', 'books', {
94+
'external_id': '1',
95+
'fields': [
96+
{'name': 'title', 'value': 'Information Retrieval', 'type': 'string'},
97+
{'name': 'genre', 'value': 'non-fiction', 'type': 'enum'},
98+
{'name': 'author', 'value': 'Stefan Buttcher', 'type': 'string'},
99+
{'name': 'in_stock', 'value': true, 'type': 'enum'},
100+
{'name': 'on_sale', 'value': false, 'type': 'enum'}
101+
]})
102+
103+
Create multiple `Document`s at once and return status for each `Document` creation:
104+
105+
stati = client.create_documents('bookstore', 'books', [{
106+
'external_id': '2',
107+
'fields': [
108+
{'name': 'title', 'value': 'Lucene in Action', 'type': 'string'},
109+
{'name': 'genre', 'value': 'non-fiction', 'type': 'enum'},
110+
{'name': 'author', 'value': 'Michael McCandless', 'type': 'string'},
111+
{'name': 'in_stock', 'value': true, 'type': 'enum'},
112+
{'name': 'on_sale', 'value': false, 'type': 'enum'}
113+
]},{
114+
'external_id': '3',
115+
'fields': [
116+
{'name': 'title', 'value': 'MongoDB in Action', 'type': 'string'},
117+
{'name': 'genre', 'value': 'non-fiction', 'type': 'enum'},
118+
{'name': 'author', 'value': 'Kyle Banker', 'type': 'string'},
119+
{'name': 'in_stock', 'value': true, 'type': 'enum'},
120+
{'name': 'on_sale', 'value': false, 'type': 'enum'}
121+
]}])
122+
123+
Update fields of an existing `Document` specified by `id` or `external_id`:
124+
125+
client.update_document('bookstore','books','1', { 'in_stock': false, 'on_sale': false })
126+
127+
Update multiple `Document`s at once:
128+
129+
stati = client.update_documents('bookstore','books', [
130+
{'external_id': '2', 'fields': {'in_stock': false}},
131+
{'external_id': '3', 'fields': {'in_stock': true}}
132+
])
133+
134+
Create or update a `Document`:
135+
136+
document = client.create_or_update_document('bookstore', 'books', {
137+
'external_id': '1',
138+
'fields': [
139+
{'name': 'title', 'value': 'Information Retrieval', 'type': 'string'},
140+
{'name': 'genre', 'value': 'non-fiction', 'type': 'enum'},
141+
{'name': 'author', 'value': 'Stefan Buttcher', 'type': 'string'},
142+
{'name': 'in_stock', 'value': false, 'type': 'enum'},
143+
{'name': 'on_sale', 'value': true, 'type': 'enum'}
144+
]})
145+
146+
Create or update multiple `Documents` at once:
147+
148+
stati = client.create_or_update_documents('bookstore', 'books', [{
149+
'external_id': '2',
150+
'fields': [
151+
{'name': 'title', 'value': 'Lucene in Action', 'type': 'string'},
152+
{'name': 'genre', 'value': 'non-fiction', 'type': 'enum'},
153+
{'name': 'author', 'value': 'Michael McCandless', 'type': 'string'},
154+
{'name': 'in_stock', 'value': false, 'type': 'enum'},
155+
{'name': 'on_sale', 'value': false, 'type': 'enum'}
156+
]},{
157+
'external_id' => '3',
158+
'fields': [
159+
{'name': 'title', 'value': 'MongoDB in Action', 'type': 'string'},
160+
{'name': 'genre', 'value': 'non-fiction', 'type': 'enum'},
161+
{'name': 'author', 'value': 'Kyle Banker', 'type': 'string'},
162+
{'name': 'in_stock', 'value': false, 'type': 'enum'},
163+
{'name': 'on_sale', 'value': false, 'type': 'enum'}
164+
]}])
165+
166+
Destroy a `Document`:
167+
168+
client.destroy_document('bookstore','books','1')
169+
170+
Destroy multiple `Document`s at once:
171+
172+
stati = client.destroy_documents('bookstore','books',['1','2','3'])
173+
174+
# Domains
175+
176+
Retrieve all `Domain`s of `Engine` `websites`:
177+
178+
domains = client.domains('websites')
179+
180+
Retrieve a specific `Domain` by `id`:
181+
182+
domain = client.domain('websites', 'generated_id')
183+
184+
Create a new `Domain` with the URL `https://swiftype.com` and start crawling:
185+
186+
domain = client.create_domain('websites', 'https://swiftype.com')
187+
188+
Delete a `Domain` using its `id`:
189+
190+
client.destroy_domain('websites', 'generated_id')
191+
192+
Initiate a recrawl of a specific `Domain` using its `id`:
193+
194+
client.recrawl_domain('websites', 'generated_id')
195+
196+
Add or update a URL for a `Domain`:
197+
198+
client.crawl_url('websites', 'generated_id', 'https://swiftype.com/new/path/about.html')
199+
200+
# Analytics
201+
202+
To get the amount of searches on your `Engine` in the last 14 days use:
203+
204+
searches = client.analytics_searches('bookstore')
205+
206+
You can also use a specific start and/or end date:
207+
208+
searches = client.analytics_searches('bookstore', '2013-01-01', '2013-02-01')
209+
210+
To get the amount of autoselects (clicks on autocomplete results) use:
211+
212+
autoselects = client.analytics_autoselects('bookstore')
213+
214+
As with searches you can also limit by start and/or end date:
215+
216+
autoselects = client.analytics_autoselects('bookstore', 2, 10)
217+
218+
If you are interested in the top queries for your `Engine` you can use:
219+
220+
top_queries = client.analytics_top_queries('bookstore')
221+
222+
To see more top queries you can paginate through them using:
223+
224+
top_queries = client.analytics_top_queries('bookstore', page=2)

0 commit comments

Comments
 (0)