[[app-search-api]]
== App Search API

=== Engines

[source,rb]
----------------------------
# Create an engine
client.create_engine(name: 'videogames')

# List all engines
client.list_engines

# Get an engine
client.engine('videogames')

# Delete an engine
client.delete_engine('videogames')
----------------------------

=== Meta engines

[source,rb]
----------------------------
# Create a meta engine:
body = {
  name: engine_name,
  type: 'meta',
  source_engines: [ 'books', 'videogames' ]
}
client.create_engine(name: engine_name, body: body)

# Add a source engine to a meta engine:
client.add_meta_engine_source(meta_engine_name, source_engines: ['engine1', 'engine2'])

# Remove a source enginge from a meta engine:
client.delete_meta_engine_source(meta_engine_name, source_engines: ['engine1', 'engine2'])
----------------------------

=== Documents

[source,rb]
----------------------------
engine_name = 'videogames'
document = {
  id: 'Mr1064',
  name: 'Super Luigi 64',
  body: 'A classic 3D videogame'
}

# Index documents
client.index_documents(engine_name, documents: document)

# List documents
client.list_documents(engine_name)

# Get document(s) by ID:
client.documents(engine_name, document_ids: [id1, id2])

# Delete a document
client.delete_documents(engine_name, document_ids: [document_id])

# Update a document
client.put_documents(engine_name, documents: [{id: document_id, key: value}])
----------------------------

=== Search

[source,rb]
----------------------------
# Single Search
query = {
  query: 'luigi'
}

client.search(engine_name, query)

# Search with multiple filters
client.search('parks', {
  body: {
    query: "olympic",
    filters: {
      all: [
        { states: "Washington" },
        { world_heritage_site: "true" }
      ]
    }
  }
})

# Multi query search
queries = [{ query: 'Nicanor'}, { query: 'Iain' }]

client.multi_search(engine_name, body: queries)

----------------------------

=== Synonym Sets

[source,rb]
----------------------------
# Create a synonym set
client.create_synonym_set(engine_name, body: {['synonym1', 'synonym2']})

# List synonym sets
client.list_synonym_sets(engine_name)

# Retrieve a synonym set by id
client.synonym_set(engine_name, synonym_set_id: 'id')

# Update a synonym set by id
client.put_synonym_set(engine_name, synonym_set_id: 'id', body: {synonyms: ['synonym2', 'synonym3']})

# Delete a synonym set
client.delete_synonym_set(engine_name, synonym_set_id: id)
----------------------------

=== Curations

[source,rb]
----------------------------
# Create a curation
client.create_curation(
         engine_name,
         queries: ['query1'],
         promoted: ['doc-id1'],
         hidden: ['doc-id2']
       )

# Retrieve a curation by id:
client.curation(engine_name, curation_id: 'cur-id')

# Update an existing curation:
client.put_curation(
  engine_name,
  curation_id: 'cur-id',
  queries: ['query1'],
  promoted: ['doc-id2'],
  hidden: ['doc-id1']
)

# List existing curations:
client.list_curations(engine_name)

# Delete a curation:
client.delete_curation(engine_name, curation_id: 'cur-id')
----------------------------

=== Other API Endpoints

[source,rb]
----------------------------
# Count analytics - Returns the number of clicks and total number of queries over a period
client.count_analytics(engine_name)

# Schema - Retrieve current schema for the engine
client.schema(engine_name)

# Update schema for an engine
client.put_schema(engine_name, schema: {field: 'type'})

# Logs - The API Log displays API request and response data at the Engine level
client.api_logs(engine_name, from_date: Date.new(2020, 10, 01), to_date: Date.new(2020, 11, 05))

# Queries Analytics - Returns queries analytics by usage count
client.top_queries_analytics(engine_name)

# Clicks Analytics - Returns the number of clicks received by a document in descending order
client.top_clicks_analytics(engine_name, query: {})

# Search Settings - Returns current search settings for an engine
client.search_settings(engine_name)

# Update Search Settings
client.put_search_settings(engine_name, body: body)

# Reset search settings
# Warning: This means your settings are wiped! Back them up!
client.reset_search_settings(engine_name)

# Click - Send data about clicked results
client.log_clickthrough(engine_name, query_text: 'query', document_id: 'doc-id')

# Query Suggestion - Provide relevant query suggestions for incomplete queries
client.query_suggestion(engine_name, query: 'incomplete_query')
----------------------------