NAME
WebService::Algolia - Algolia API Bindings
VERSION
version 0.1002
SYNOPSIS
use WebService::Algolia;
my $alg = WebService::Algolia->new(
application_id => '12345',
api_key => 'abcde',
);
$alg->get_indexes;DESCRIPTION
This module provides bindings for the Algolia API.
METHODS
new
Instantiates a new WebService::Algolia client object.
my $alg = WebService::Algolia->new(
application_id => $application_id,
api_key => $api_key,
timeout => $retries, # optional
retries => $retries, # optional
);Parameters
- -
application_id -
Required
A valid Algolia application ID for your account.
- -
api_key -
Required
A valid Algolia api key for your account.
- -
timeout -
Optional
The number of seconds to wait per request until timing out. Defaults to
10. - -
retries -
Optional
The number of times to retry requests in cases when Lob returns a 5xx response. Defaults to
0.
get_indexes
Returns a list of all existing indexes.
Request:
get_indexes();Response:
[{
createdAt => "2014-12-03T23:20:19.745Z",
dataSize => 42,
entries => 1,
lastBuildTimeS => 0,
name => "foo",
pendingTask => bless(do{\(my $o = 0)}, "JSON::PP::Boolean"),
updatedAt => "2014-12-04T00:41:14.120Z",
},
{
createdAt => "2014-12-03T23:20:18.323Z",
dataSize => 36,
entries => 1,
lastBuildTimeS => 0,
name => "bar",
pendingTask => bless(do{\(my $o = 0)}, "JSON::PP::Boolean"),
updatedAt => "2014-12-04T00:42:13.231Z",
}]browse_index
Returns all content from an index.
Request:
browse_index('foo');Response:
{
hits => [{ bar => { baz => "bat" }, objectID => 5333220 }],
hitsPerPage => 1000,
nbHits => 1,
nbPages => 1,
page => 0,
params => "hitsPerPage=1000&attributesToHighlight=&attributesToSnippet=&attributesToRetrieve=*",
processingTimeMS => 1,
query => "",
}query_index
Returns objects that match the query.
Request:
query_index({ index => 'foo', query => 'bat' });Response:
{
hits => [
{ _highlightResult => {
bar => {
baz => {
matchedWords => [ "bat" ],
matchLevel => "full",
value => "<em>bat</em>"
},
},
},
bar => { baz => "bat" },
objectID => 5333370,
},
],
hitsPerPage => 20,
nbHits => 1,
nbPages => 1,
page => 0,
params => "query=bat",
processingTimeMS => 1,
query => "bat",
}query_indexes
Query multiple indexes with one API call.
Request:
query_indexes([
{ index => 'foo', query => 'baz' },
{ index => 'foo', query => 'bat' },
]);Response:
{
results => [
{ hits => [],
hitsPerPage => 20,
index => "foo",
nbHits => 0,
nbPages => 0,
page => 0,
params => "query=baz",
processingTimeMS => 1,
query => "baz",
},
{ hits => [
{ _highlightResult => {
bar => {
baz => {
matchedWords => [ "bat" ],
matchLevel => "full",
value => "<em>bat</em>"
},
},
},
bar => { baz => "bat" },
objectID => 5333380,
},
],
hitsPerPage => 20,
index => "foo",
nbHits => 1,
nbPages => 1,
page => 0,
params => "query=bat",
processingTimeMS => 1,
query => "bat",
},
],
}clear_index
Deletes the index content. Settings and index specific API keys are kept untouched.
Request:
clear_index('foo');Response:
{
taskID => 26036480,
updatedAt => "2014-12-04T00:53:40.957Z",
}copy_index
Copies an existing index. If the destination index already exists, its specific API keys will be preserved and the source index specific API keys will be added.
Request:
copy_index('foo' => 'foo2');Response:
{
taskID => 26071750,
updatedAt => "2014-12-04T01:16:20.307Z",
}move_index
Moves an existing index. If the destination index already exists, its specific API keys will be preserved and the source index specific API keys will be added.
Request:
move_index('foo' => 'foo2');Response:
{
taskID => 26079100,
updatedAt => "2014-12-04T01:21:01.815Z",
}delete_index
Deletes an existing index.
Request:
delete_index('foo');Response:
{
taskID => 26040530,
deletedAt => "2014-12-04T00:56:00.773Z",
}get_index_settings
Retrieves index settings.
Request:
get_index_settings('foo');Response:
{
'attributeForDistinct' => undef,
'attributesForFaceting' => undef,
'attributesToHighlight' => undef,
'attributesToIndex' => [ 'bat' ],
'attributesToRetrieve' => undef,
'attributesToSnippet' => undef,
'customRanking' => undef,
'highlightPostTag' => '</em>',
'highlightPreTag' => '<em>',
'hitsPerPage' => 20,
'minWordSizefor1Typo' => 4,
'minWordSizefor2Typos' => 8,
'optionalWords' => undef,
'queryType' => 'prefixLast',
'ranking' => [
'typo',
'geo',
'words',
'proximity',
'attribute',
'exact',
'custom'
],
'removeWordsIfNoResults' => 'none',
'separatorsToIndex' => '',
'unretrievableAttributes' => undef
}update_index_settings
Updates part of an index's settings.
Request:
update_index_settings('foo', { attributesToIndex => ['bat'] });Response:
{
taskID => 27224430,
updatedAt => "2014-12-04T19:52:29.54Z",
}create_index_object
Creates a new object in the index, and automatically assigns an Object ID.
Request:
create_index_object('foo', { bar => { baz => 'bat' }});Response:
{
objectID => 5333250,
taskID => 26026500,
createdAt => "2014-12-04T00:47:21.781Z",
}get_index_object
Returns one object from the index.
Request:
get_index_object('foo', 5333250);Response:
{
objectID => 5333250,
delicious => 'limoncello',
}get_index_objects
Retrieve several objects with one API call.
Request:
get_index_objects([
{ index => 'foo', object => 5333250 },
{ index => 'foo', object => 5333251 },
]);Response:
{
results => [{
objectID => 5333250,
delicious => 'limoncello',
},
{
objectID => 5333251,
terrible => 'cabbage',
}],
}replace_index_object
Creates or replaces an object (if the object does not exist, it will be created). When an object already exists for the specified object ID, the whole object is replaced: existing attributes that are not replaced are deleted.
Request:
replace_index_object('foo', 5333250, { delicious => 'limoncello' });Response:
{
objectID => 5333250,
taskID => 26034540,
updatedAt => "2014-12-04T00:52:32.416Z",
}update_index_object
Updates part of an object (if the object does not exist, it will be created. You can avoid an automatic creation of the object by passing createIfNotExists=false as a query argument).
Request:
update_index_object('foo', 5333251, { another => 'pilsner?' });Response:
{
objectID => 5333251,
taskID => 29453760,
updatedAt => "2014-12-06T02:49:40.859Z",
}delete_index_object
Deletes an existing object from the index.
Request:
delete_index_object('foo', 5333251);Response:
{
objectID => 5333251,
taskID => 29453761,
deletedAt => "2014-12-11T02:49:40.859Z",
}batch_index_objects
To reduce the amount of time spent on network round trips, you can create, update, or delete several objects in one call, using the batch endpoint (all operations are done in the given order).
The following methods can be passed into the batch_index_objects method as anonymous subroutines: create_index_object, update_index_object, replace_index_object, and delete_index_object.
Request:
alg->batch_index_objects('foo', [
sub { alg->create_index_object('foo', { hello => 'world' })},
sub { alg->create_index_object('foo', { goodbye => 'world' })},
]);Response:
{
objectIDs => [5698830, 5698840],
taskID => 40684520,
}Request:
alg->batch_index_objects('foo', [
sub { alg->update_index_object('foo', 5698830, { 1 => 2 })},
sub { alg->update_index_object('foo', 5698840, { 3 => 4 })},
]);Response:
{
objectIDs => [5698830, 5698840],
taskID => 40684521,
}Request:
alg->batch_index_objects('foo', [
sub { alg->delete_index_object('foo', 5698830 )},
sub { alg->delete_index_object('foo', 5698840 )},
]);Response:
{
objectIDs => [5698830, 5698840],
taskID => 40684522,
}get_index_keys
If an indexName is passed, retrieves API keys that have access to this index with their rights. Otherwise, retrieves all API keys that have access to one index with their rights.
Request:
get_index_keys();Response:
{
keys => [
{
acl => [],
index => "pirouette",
validity => 0,
value => "181b9114149666398628faa37b31cc8d",
},
{
acl => ['browse'],
index => "gelato",
validity => 0,
value => "1428a48214792ac9f6324a823991aa4c",
},
],
}Request:
get_index_keys('pirouette');Response:
{
keys => [
{
acl => [],
validity => 0,
value => "181b9114149666398628faa37b31cc8d",
}
],
}get_index_key
Returns the rights of a given index specific API key that has been created with the add index specific key API.
Request:
get_index_key('pirouette', '181b9114149666398628faa37b31cc8d');Response:
{
acl => [],
validity => 0,
value => "181b9114149666398628faa37b31cc8d",
}create_index_key
Adds a new key that can access this index.
Request:
create_index_key('pirouette', { acl => ['search']});Response:
{
createdAt => "2014-12-08T15:54:22.464Z",
key => "181b9114149666398628faa37b31cc8d",
}update_index_key
Updates a key that can access this index.
Request:
update_index_key('pirouette', '181b9114149666398628faa37b31cc8d', { acl => ['search', 'browse']});Response:
{
updatedAt => "2014-12-08T16:39:11.9Z",
key => "181b9114149666398628faa37b31cc8d",
}delete_index_key
Deletes an index specific API key that has been created with the add index specific key API.
Request:
delete_index_key('pirouette', '181b9114149666398628faa37b31cc8d');Response:
{
deletedAt => "2014-12-08T16:40:49.86Z",
}get_task_status
Retrieves the status of a given task (published or notPublished). Also returns a pendingTask flag that indicates if the index has remaining task(s) running.
Request:
get_task_status('foo', 29734242);Response:
{
pendingTask => bless(do{\(my $o = 0)}, "JSON::PP::Boolean"),
status => "published",
}get_keys
Retrieves global API keys with their rights. These keys have been created with the add global key API.
Request:
get_keys();Response:
{
keys => [
{
acl => [],
validity => 0,
value => "28b555c212728a7f462fe96c0e677539",
},
{
acl => [],
validity => 0,
value => "6ef88c72a6a4fc7e660f8819f111697c",
}
],
}get_key
Returns the rights of a given global API key that has been created with the add global Key API.
Request:
get_key('28b555c212728a7f462fe96c0e677539');Response:
{
acl => [],
validity => 0,
value => "28b555c212728a7f462fe96c0e677539",
}update_key
Updates a global API key.
Request:
update_key('28b555c212728a7f462fe96c0e677539', { acl => ['search', 'browse']});Response:
{
updatedAt => "2014-12-08T16:39:11.9Z",
key => "28b555c212728a7f462fe96c0e677539",
}delete_key
Deletes a global API key that has been created with the add global Key API.
Request:
delete_key('28b555c212728a7f462fe96c0e677539');Response:
{
deletedAt => "2014-12-08T16:40:49.86Z",
}get_logs
Return last logs.
Request:
get_logs();Response:
{
logs => [
{
answer => "\n{\n \"keys\": [\n ]\n}\n",
answer_code => 200,
ip => "199.91.170.132",
method => "GET",
nb_api_calls => 1,
processing_time_ms => 1,
query_body => "",
query_headers => "TE: deflate,gzip;q=0.3\nConnection: TE, close\nHost: 9KV4OFXW8Z.algolia.io\nUser-Agent: libwww-perl/6.08\nContent-Type: application/json\nX-Algolia-API-Key: 28d*****************************\nX-Algolia-Application-Id: 9KV4OFXW8Z\n",
sha1 => "b82f8d002ccae799f6629300497725faa670cc7b",
timestamp => "2014-12-09T05:08:05Z",
url => "/1/keys",
},
{
answer => "\n{\n \"value\": \"3bfccc91bb844f5ba0fc816449a9d340\",\n \"acl\": [\n \"search\"\n ],\n \"validity\": 0\n}\n",
answer_code => 200,
ip => "199.91.170.132",
method => "GET",
nb_api_calls => 1,
processing_time_ms => 1,
query_body => "",
query_headers => "TE: deflate,gzip;q=0.3\nConnection: TE, close\nHost: 9KV4OFXW8Z.algolia.io\nUser-Agent: libwww-perl/6.08\nContent-Type: application/json\nX-Algolia-API-Key: 28d*****************************\nX-Algolia-Application-Id: 9KV4OFXW8Z\n",
sha1 => "4915e88a309ea42f8f0ee46c9358b57b9a37a3d9",
timestamp => "2014-12-09T05:08:04Z",
url => "/1/keys/3bfccc91bb844f5ba0fc816449a9d340",
},
],
}Request:
get_logs({
offset => 4,
length => 2,
});Response:
{
logs => [
{
answer => "\n{\n \"message\": \"Key does not exist\"\n}\n",
answer_code => 404,
index => "pirouette",
ip => "50.243.54.51",
method => "GET",
nb_api_calls => 1,
processing_time_ms => 1,
query_body => "",
query_headers => "TE: deflate,gzip;q=0.3\nConnection: TE, close\nHost: 9KV4OFXW8Z.algolia.io\nUser-Agent: libwww-perl/6.07\nContent-Type: application/json\nX-Algolia-API-Key: 28d*****************************\nX-Algolia-Application-Id: 9KV4OFXW8Z\n",
sha1 => "e2d3de10f69d8efb16caadaa22c6312ac408ed48",
timestamp => "2014-12-08T16:06:32Z",
url => "/1/indexes/pirouette/keys/25c005baabd13ab5c3ac14a79c9d5c27",
},
{
answer => "\n{\n \"message\": \"Key does not exist\"\n}\n",
answer_code => 404,
index => "pirouette",
ip => "50.243.54.51",
method => "GET",
nb_api_calls => 1,
processing_time_ms => 1,
query_body => "",
query_headers => "TE: deflate,gzip;q=0.3\nConnection: TE, close\nHost: 9KV4OFXW8Z.algolia.io\nUser-Agent: libwww-perl/6.07\nContent-Type: application/json\nX-Algolia-API-Key: 28d*****************************\nX-Algolia-Application-Id: 9KV4OFXW8Z\n",
sha1 => "d0799be3ccf05d2d5a0c902f6e80917468d5e6ff",
timestamp => "2014-12-08T16:06:07Z",
url => "/1/indexes/pirouette/keys/b7fbe3bcc26322af222edf2a9ca934ee",
},
],
}get_popular_searches
Return popular queries for a set of indices.
Request:
get_popular_searches(['foo']);Response:
{
lastSearchAt => "2014-12-09T05:00:00.000Z",
searchCount => 48,
topSearches => [
{
avgHitCount => 0,
avgHitCountWithoutTypos => 0,
count => 32,
query => "bat"
},
],
}get_unpopular_searches
Return queries matching 0 records for a set of indices.
Request:
get_unpopular_searches(['foo']);Response:
{
lastSearchAt => "2014-12-09T05:00:00.000Z",
searchCount => 48,
topSearchesNoResuls => [ { count => 16, query => "baz" } ],
}SEE ALSO
https://www.algolia.com/doc - the API documentation for https://www.algolia.com.
BUGS
Please report any bugs or feature requests on the bugtracker website https://github.com/aanari/WebService-Algolia/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
AUTHOR
Ali Anari <ali@anari.me>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by Ali Anari.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.