Skip to content

Commit 61ed575

Browse files
author
Tobias Hauth
committed
add quickstart
1 parent c3a277c commit 61ed575

File tree

1 file changed

+168
-94
lines changed

1 file changed

+168
-94
lines changed

‎README.md

Lines changed: 168 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,80 @@
11
Swiftype API Client for Python
22
===============================
33

4-
# Configuration:
4+
# Quickstart
5+
6+
## Setup
7+
8+
1. Create an account at [Swiftype](https://swiftype.com/) and get your API key from your [Account Settings](https://swiftype.com/user/edit).
9+
10+
2. Configure your client:
11+
12+
import swiftype
13+
client = swiftype.Client(api_key='YOUR_API_KEY')
14+
15+
3. Create an `Engine` named e.g. `youtube`:
16+
17+
engine = client.create_engine('youtube')
18+
19+
4. Create your `DocumentType`s:
20+
21+
client.create_document_type('youtube', 'videos');
22+
client.create_document_type('youtube', 'channels');
23+
24+
## Indexing
25+
26+
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](https://swiftype.com/documentation/overview#field_types).
27+
28+
Add a `Document` to the `videos` `DocumentType`:
29+
30+
client.create_document('youtube', 'videos', {
31+
'external_id': 'external_id1',
32+
'fields': [
33+
{'name': 'title', 'value': 'Swiftype Demo', 'type': 'string'},
34+
{'name': 'tags', 'value': ['Swiftype', 'Search', 'Full text search'], 'type': 'string'},
35+
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=pITuOcGgpBs', 'type': 'enum'},
36+
{'name': 'category', 'value': ['Tutorial', 'Product'], 'type': 'enum'},
37+
{'name': 'publication_date', 'value': '2012-05-08T12:07Z', 'type': 'date'},
38+
{'name': 'likes', 'value': 31, 'type': 'integer'},
39+
{'name': 'length', 'value': 1.50, 'type': 'float'}
40+
]})
41+
42+
Add a `Document` to the `users` `DocumentType`:
43+
44+
client.create_document('youtube', 'channels', {
45+
'external_id': 'external_id1',
46+
'fields': [
47+
{'name': 'title', 'value': 'Swiftype', 'type': 'string'},
48+
{'name': 'url', 'value': 'http://www.youtube.com/user/swiftype', 'type': 'enum'},
49+
{'name': 'video_views', 'value': 15678, 'type': 'integer'},
50+
{'name': 'video_counts', 'value': 6, 'type': 'integer'}
51+
]})
52+
53+
## Searching
54+
55+
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:
56+
57+
video_results = client.search_document_type('youtube', 'videos', 'swiftype')
58+
channel_results = client.search_document_type('youtube', 'channels', 'swiftype')
59+
60+
or search all `DocumentType`s on your `Engine` at once:
61+
62+
results = client.search('youtube', 'swiftype')
63+
64+
## Autocomplete
65+
66+
Finally, as with full-text searches, you may perform autocomplete-style (prefix match) searches as well:
67+
68+
results = client.suggest('youtube', 'swi')
69+
70+
or
71+
72+
results = client.suggest_document_type('youtube', 'videos', 'swi')
73+
74+
75+
# API Documentation
76+
77+
## Configuration:
578

679
Before issuing commands to the API, configure the client with your API key:
780

@@ -10,168 +83,169 @@ Before issuing commands to the API, configure the client with your API key:
1083

1184
You can find your API key in your [Account Settings](https://swiftype.com/user/edit).
1285

13-
# Search
86+
## Search
1487

15-
If you want to search for e.g. `action` on your engine, you can use:
88+
If you want to search for e.g. `swiftype` on your `Engine`, you can use:
1689

17-
results = client.search('bookstore', 'action')
90+
results = client.search('youtube', 'swiftype')
1891

19-
To limit the search to only the `books` DocumentType:
92+
To limit the search to only the `videos` DocumentType:
2093

21-
results = client.search_document_type('bookstore', 'books', 'action')
94+
results = client.search_document_type('youtube', 'videos', 'swiftype')
2295

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:
96+
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](https://swiftype.com/documentation/searching). Here is an example for showing only `videos` that are in the `category` `Tutorial`:
2497

25-
results = client.search_document_type('bookstore', 'books', 'action', {'filters': {'books': {'in_stock': true}}})
98+
results = client.search_document_type('youtube', 'videos', 'swiftype', {'filters': {'videos': {'category': 'Tutorial'}}})
2699

27-
# Autocomplete
100+
## Autocomplete
28101

29102
Autocompletes have the same functionality as searches. You can autocomplete using all documents:
30103

31-
results = client.suggest('bookstore', 'acti')
104+
results = client.suggest('youtube', 'swi')
32105

33106
or just for one DocumentType:
34107

35-
results = client.suggest_document_type('bookstore', 'books', 'acti')
108+
results = client.suggest_document_type('youtube', 'videos', 'swi')
36109

37110
or add options to have more control over the results:
38111

39-
results = client.suggest('bookstore', 'acti', {'sort_field': {'books': 'price'}})
112+
results = client.suggest('youtube', 'swi', {'sort_field': {'videos': 'likes'}})
40113

41-
# Engines
114+
## Engines
42115

43116
Retrieve every `Engine`:
44117

45118
engines = client.engines
46119

47-
Create a new `Engine` with the name `bookstore`:
120+
Create a new `Engine` with the name `youtube`:
48121

49-
engine = client.create_engine('bookstore')
122+
engine = client.create_engine('youtube')
50123

51124
Retrieve an `Engine` by `slug` or `id`:
52125

53-
engine = client.engine('bookstore')
126+
engine = client.engine('youtube')
54127

55128
To delete an `Engine` you need the `slug` or the `id` field of an `engine`:
56129

57-
client.destroy_engine('bookstore')
130+
client.destroy_engine('youtube')
58131

59-
# Document Types
132+
## Document Types
60133

61-
Retrieve `DocumentTypes`s of the `Engine` with the `slug` field `bookstore`:
134+
Retrieve `DocumentTypes`s of the `Engine` with the `slug` field `youtube`:
62135

63-
document_types = client.document_types('bookstore')
136+
document_types = client.document_types('youtube')
64137

65138
Show the second batch of documents:
66139

67-
document_types = client.document_types('bookstore', 2)
140+
document_types = client.document_types('youtube', 2)
68141

69-
Create a new `DocumentType` for an `Engine` with the name `books`:
142+
Create a new `DocumentType` for an `Engine` with the name `videos`:
70143

71-
document_type = client.create_document_type('bookstore', 'books')
144+
document_type = client.create_document_type('youtube', 'videos')
72145

73146
Retrieve an `DocumentType` by `slug` or `id`:
74147

75-
document_type = client.document_type('bookstore', 'books')
148+
document_type = client.document_type('youtube', 'videos')
76149

77150
Delete a `DocumentType` using the `slug` or `id` of it:
78151

79-
client.destroy_document_type('bookstore', 'books')
152+
client.destroy_document_type('youtube', 'videos')
80153

81-
# Documents
154+
## Documents
82155

83-
Retrieve all `Document`s of `Engine` `bookstore` and `DocumentType` `books`:
156+
Retrieve all `Document`s of `Engine` `youtube` and `DocumentType` `videos`:
84157

85-
documents = client.documents('bookstore', 'books')
158+
documents = client.documents('youtube', 'videos')
86159

87160
Retrieve a specific `Document` using its `id` or `external_id`:
88161

89-
document = client.document('bookstore', 'books', 'id1')
162+
document = client.document('youtube', 'videos', 'external_id1')
90163

91164
Create a new `Document` with mandatory `external_id` and user-defined fields:
92165

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-
]})
166+
document = client.create_document('youtube', 'videos', {
167+
'external_id': 'external_id1',
168+
'fields': [
169+
{'name': 'title', 'value': 'Swiftype Demo', 'type': 'string'},
170+
{'name': 'tags', 'value': ['Swiftype', 'Search', 'Full text search'], 'type': 'string'},
171+
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=pITuOcGgpBs', 'type': 'enum'},
172+
{'name': 'category', 'value': ['Tutorial', 'Product'], 'type': 'enum'},
173+
{'name': 'publication_date', 'value': '2012-05-08T12:07Z', 'type': 'date'},
174+
{'name': 'likes', 'value': 31, 'type': 'integer'},
175+
{'name': 'length', 'value': 1.50, 'type': 'float'}
176+
]})
102177

103178
Create multiple `Document`s at once and return status for each `Document` creation:
104179

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-
]}])
180+
stati = client.create_documents('youtube', 'videos', {
181+
'external_id': 'external_id1',
182+
'fields': [
183+
{'name': 'title', 'value': 'Swiftype Demo', 'type': 'string'},
184+
{'name': 'tags', 'value': ['Swiftype', 'Search', 'Full text search'], 'type': 'string'},
185+
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=pITuOcGgpBs', 'type': 'enum'},
186+
{'name': 'category', 'value': ['Tutorial', 'Product'], 'type': 'enum'},
187+
{'name': 'publication_date', 'value': '2012-05-08T12:07Z', 'type': 'date'},
188+
{'name': 'likes', 'value': 27, 'type': 'integer'},
189+
{'name': 'length', 'value': 1.50, 'type': 'float'}
190+
]}, {
191+
'external_id': 'external_id2',
192+
'fields': [
193+
{'name': 'title', 'value': 'Swiftype Search Wordpress Plugin Demo', 'type': 'string'},
194+
{'name': 'tags', 'value': ['Swiftype', 'Search', 'Full text search', 'WordPress'], 'type': 'string'},
195+
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=rukXYKEpvS4', 'type': 'enum'},
196+
{'name': 'category', 'value': ['Tutorial', 'Wordpress'], 'type': 'enum'},
197+
{'name': 'publication_date', 'value': '2012-08-15T09:07Z', 'type': 'date'},
198+
{'name': 'likes', 'value': 2, 'type': 'integer'},
199+
{'name': 'length', 'value': 2.16, 'type': 'float'}
200+
]})
122201

123202
Update fields of an existing `Document` specified by `id` or `external_id`:
124203

125-
client.update_document('bookstore','books','1', { 'in_stock': false, 'on_sale': false })
204+
client.update_document('youtube','videos','external_id1', {'likes': 28, 'category': ['Tutorial', 'Search']})
126205

127206
Update multiple `Document`s at once:
128207

129-
stati = client.update_documents('bookstore','books', [
130-
{'external_id': '2', 'fields': {'in_stock': false}},
131-
{'external_id': '3', 'fields': {'in_stock': true}}
208+
stati = client.update_documents('youtube', 'videos', [
209+
{'external_id': '2', 'fields': {'likes': 29}},
210+
{'external_id': '3', 'fields': {'likes': 4}}
132211
])
133212

134213
Create or update a `Document`:
135214

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'}
215+
document = client.create_or_update_document('youtube', 'videos', {
216+
'external_id': 'external_id3',
217+
'fields': [
218+
{'name': 'title', 'value': 'Swiftype Install Type 1: Show results in an overlay', 'type': 'string'},
219+
{'name': 'tags', 'value': ['Swiftype', 'Search', 'Full text search', 'Web'], 'type': 'string'},
220+
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=mj2ApIx3frs', 'type': 'enum'}
144221
]})
145222

146223
Create or update multiple `Documents` at once:
147224

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-
]}])
225+
stati = client.create_or_update_documents('youtube', 'videos', {
226+
'external_id': 'external_id4',
227+
'fields': [
228+
{'name': 'title', 'value': 'Swiftype Install Type 2: Show results on the current page', 'type': 'string'},
229+
{'name': 'tags', 'value': ['Swiftype', 'Search', 'Full text search', 'Web'], 'type': 'string'},
230+
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=6uaZXYK2WOE', 'type': 'enum'}
231+
]}, {
232+
'external_id': 'external_id5',
233+
'fields': [
234+
{'name': 'title', 'value': 'Swiftype Install Type 3: Show results on a new page', 'type': 'string'},
235+
{'name': 'tags', 'value': ['Swiftype', 'Search', 'Full text search', 'Web'], 'type': 'string'},
236+
{'name': 'url', 'value': 'http://www.youtube.com/watch?v=ebSWAscBPtc', 'type': 'enum'}
237+
]});
238+
165239

166240
Destroy a `Document`:
167241

168-
client.destroy_document('bookstore','books','1')
242+
client.destroy_document('youtube','videos','external_id5')
169243

170244
Destroy multiple `Document`s at once:
171245

172-
stati = client.destroy_documents('bookstore','books',['1','2','3'])
246+
stati = client.destroy_documents('youtube','videos',['external_id2','external_id3','external_id6'])
173247

174-
# Domains
248+
## Domains
175249

176250
Retrieve all `Domain`s of `Engine` `websites`:
177251

@@ -197,28 +271,28 @@ Add or update a URL for a `Domain`:
197271

198272
client.crawl_url('websites', 'generated_id', 'https://swiftype.com/new/path/about.html')
199273

200-
# Analytics
274+
## Analytics
201275

202276
To get the amount of searches on your `Engine` in the last 14 days use:
203277

204-
searches = client.analytics_searches('bookstore')
278+
searches = client.analytics_searches('youtube')
205279

206280
You can also use a specific start and/or end date:
207281

208-
searches = client.analytics_searches('bookstore', '2013-01-01', '2013-02-01')
282+
searches = client.analytics_searches('youtube', '2013-01-01', '2013-02-01')
209283

210284
To get the amount of autoselects (clicks on autocomplete results) use:
211285

212-
autoselects = client.analytics_autoselects('bookstore')
286+
autoselects = client.analytics_autoselects('youtube')
213287

214288
As with searches you can also limit by start and/or end date:
215289

216-
autoselects = client.analytics_autoselects('bookstore', 2, 10)
290+
autoselects = client.analytics_autoselects('youtube', 2, 10)
217291

218292
If you are interested in the top queries for your `Engine` you can use:
219293

220-
top_queries = client.analytics_top_queries('bookstore')
294+
top_queries = client.analytics_top_queries('youtube')
221295

222296
To see more top queries you can paginate through them using:
223297

224-
top_queries = client.analytics_top_queries('bookstore', page=2)
298+
top_queries = client.analytics_top_queries('youtube', page=2)

0 commit comments

Comments
 (0)