Searchbar.org API Reference

Este documento detalha as principais rotas da API para usuário desenvolvedor e integração com o Searchbar.

Antes de começar

A Url base da API do Searchbar é

https://api.searchbar.org/v1

Erros Genéricos

Código	Descrição
401	Usuário não autorizado ou token inválida
400	Request mal formado
422	Payload/json com campos faltantes

Todos os requests possuem Rate Control (a fim de evitar ataques DDoS). Portanto, considere o limite de 3 requests simultâneos, aguardando a resposta para iniciar novos requests.

Autenticação

Para ter acesso à API Searchbar é necessário obter uma token de autorização, que deve ser incluída como Bearer Token no cabeçalho "Authentication" em todos os demais requests.

"Authorization" : "Bearer [sua_token_de_authorização]"

POST /account/login

{
    "email": "seuemail@exemplo.com",
    "password": "suasenha"
}

Parâmetro	Tipo	Descrição
email	String	O email da sua conta Searchbar
password	String	A senha da sua conta Searchbar

Exemplo Retorno

{
    "user": "meuemail@exemplo.com",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCJ6IkpXVCJ9.eyJpZCI6IjViZWM2MzIxN2IartcwMjJlMDU3OGNlMyIsInRva2VuVHlwZSI6InByaXZhdGUiLCJyb2xlIjoiQURNSU4iLCJpYXQiOjE1OTE2NzYwNjksImV4cCI6MTU5MTc2MjQ2OX0.Gotjepi8xfa8oakzVg2eMkEm3GMpCuNvmkdcJejJEyc",
    "publicToken": "eyJhbGciOiJIUzI1NiPirnR5cCI6IkpXVCJ9.eyJpZCI6IjViZWM2MzIxN2IwYTcwMfg45sU3OGNlMyIsInRva2VuVHlwZSI6InB1YmxpYyIsImlhdCI6MTU5MTY3NjA2OSwiZXhwIjoxNTkxNzYyNDY5fQ.Ve68IS19aMrddWf800V1eDCKa_vy8Kqvek5UDT0o7b0",
    "expirationDate": "2020-04-21T04:14:29.000Z"
}

Parâmetro	Tipo	Descrição
user	String	O email da sua conta Searchbar
token	String	Sua token privada para utilização da API. Não publique ou compartilhe a sua token privada. Expira após 24hrs
publicToken	String	Sua token pública para utilização em ambientes públicos e no seu site. Não Expira.
expirationDate	ISO Date	Data da expiração da sua token privada. Após esse período, é necessário novo login.

GET /account/site

Retorna os sites cadastrados e indexados na sua conta.

[
    {
        "name": "Site Principal",
        "sitemap": "https://meusite.com.br/sitemap.xml",
        "site": "https://meusite.com.br",
        "active": true
    }
]

Parâmetro	Tipo	Descrição
name	String	Alias do site
sitemap	String	Caso seja informado um sitemap, ou o crowler encontre algum automaticamente, o endereço do Arquivo sitemap.xml é retornado
site	String	URL base do Site indexado
active	Boolean	Ativo ou Inativo

PUT /account/site

Define o site principal da sua conta.

Cuidado: este endpoint atualiza todas as páginas da sua conta, exceto as inseridas manualmente via POST /page.

{
    "site":"https://meunovosite.com.br"
}

Parâmetro	Tipo	Descrição
site	String	URL do site a ser indexado

GET /page/

Efetua uma busca por texto nas páginas indexadas na sua conta

GET /page/?q=termo&offset=0&size=10&tag=news

Parâmetro	Tipo	Descrição
q	String	Query a ser buscada
offset	Number	Define o offset de paginação para retornar a busca
size	Number	Define a quantidade de resultados por página retornada (máximo 100)
tag	String	Se definida, filtra os resultados pela tag informada. Pode ser adicionada mais de uma tag à URL.

Exemplo de Retorno

{
    {
        "term": "termo",
        "total": 61,
        "from": "0",
        "to": 10,
        "tags": [
                {
                    "key": "news",
                    "doc_count": 25
                }
            ],
        "results": [
            {
                "_index": "pages",
                "_type": "page",
                "_id": "5edf0eded584ee21c924c732",
                "_score": 2,
                "_source": {
                    "url": "https://meunovosite.com.br/about-us/",
                    "account": "5bec63217b0a7022e0578ce3",
                    "status": "PROCESSED",
                    "origin": "SITEMAP",
                    "weight": 1,
                    "description": "This is the page result description...",
                    "title": "Page Title"
                },
                "highlight": {
                    "description.special": [
                        "This is a <em>highlighted</em> text description..."
                    ]
                }
            }
        }
    }
}

Parâmetro	Tipo	Descrição
term	String	Termo buscado
total	Number	Quantidade total de páginas encontradas que atendem ao termo buscado
from	Number	Início da paginação atual
to	Number	Fim da paginação atual
tags	Array	Lista de tags relacionadas aos resultados e suas quantidades
results	Array	Lista de Resultados

POST /page/

Insere páginas customizadas ou atualiza páginas existentes.

Importante: O tamanho do Payload não deve ultrapassar 500 KBs.

{
    "pages": [
        {
            "url": "http://example.com/1",
            "title": "This is a title example",
            "description": "This is the description from the page. It can be a large text."
        },
        {
            "url": "http://example.com/2",
            "title": "This is a title example 2",
            "description": "This is the description from the page. It can be a large text.",
            "tags": ["blog", "news"],
            "image": "https://upload.wikimedia.org/wikipedia/commons/b/b6/Image_created_with_a_mobile_phone.png"
        },
        {
            "url": "http://example.com/3",
            "title": "This is a title example 3 ",
            "description": "This is the description from the page. It can be a large text.",
            "weight": "2"
        }
    ]
}

Parâmetro	Tipo	Descrição
pages	Array	Array de Pages
url	String	URL da página a ser adicionada (Obrigatório)
title	String	Título da página a ser adicionada (Obrigatório)
description	String	Descrição da página a ser adicionada
tags	String Array	Tags opcionais para classificar páginas
weight	Number	Peso da página. Páginas multiplicam seu score com o seu peso para se tornarem artificialmente mais relevantes.

DELETE /page/

Remove a lista de páginas enviadas ou remove todas as páginas

{
    "deleteAll": false,
    "deleteList": [
        "http://example.com/1",
        "http://example.com/2",
        "http://example.com/3",
        "http://example.com/5"
    ]
}

Parâmetro	Tipo	Descrição
deleteAll	Boolean	Quando true, remove todas as páginas indexadas na conta
deleteList	Array	Lista com as URLs das páginas a serem deletadas

Snippets

Maiquel Ludwig Searchbar API Reference