# Bem-vindo!

AwesomeAPI tem um único propósito, oferecer um serviço funcional, simples e acessível.

Para informações sobre preços e limites acesse [www.awesomeapi.com.br](https://awesomeapi.com.br)


# API de Cotações

API de Cotações em tempo real com mais de 150 moedas!

**Para evitar o cache e ter acesso aos dados em tempo real, cadastre-se no** [**awesomeapi.com.br**](https://awesomeapi.com.br) **e tenha até 100.000 requisições gratuitas!**

Para garantir acesso aos dados em tempo real sem interferência de cache, utilize sua API Key. Para mais informações sobre como obter e configurar sua API Key, visite [as instruções de API Key](/instrucoes-api-key).

### Códigos das moedas:

Veja a lista completa de combinações em <https://economia.awesomeapi.com.br/xml/available>

Veja a lista de nomes das moedas <https://economia.awesomeapi.com.br/xml/available/uniq>

### **Outras conversões**

#### Cotação Turismo

* USD-BRLT (Dólar Americano para Real Brasileiro Turismo)
* EUR-BRLT (Euro para Real Brasileiro Turismo)

#### Cotação PTAX (Dados do Banco Central)

A cotação PTAX é uma taxa de câmbio calculada pelo Banco Central do Brasil, que representa a média das taxas de compra e venda do dólar, apuradas ao longo do dia em que há operações de câmbio, ajustadas ao final desse período. Ela é comumente utilizada como referência para contratos financeiros e serve como base para a conversão de valores entre moedas, oferecendo um benchmark confiável para transações cambiais.<br>

* USD-BRLPTAX (Dólar Americano para Real Brasileiro)
* EUR-BRLPTAX (Euro para Real Brasileiro)

## Retorna moedas selecionadas (atualizado em tempo real\*)

<mark style="color:blue;">`GET`</mark> `https://economia.awesomeapi.com.br/json/last/:moedas`

Retorna a ultima ocorrência das moedas selecionadas.\
Ex.: **<https://economia.awesomeapi.com.br/last/USD-BRL,EUR-BRL,BTC-BRL>**

**\*Solicitações não autenticadas com chave de API serão armazenadas em cache por 1 minuto.**

#### Path Parameters

| Name   | Type   | Description                                                               |
| ------ | ------ | ------------------------------------------------------------------------- |
| moedas | string | Moedas selecionadas separado por vírgula (,) Ex.: USD-BRL,EUR-BRL,BTC-BRL |

{% tabs %}
{% tab title="200 " %}

```
{
    "USDBRL": {
        "code": "USD",
        "codein": "BRL",
        "name": "Dólar Americano/Real Brasileiro",
        "high": "5.734",
        "low": "5.7279",
        "varBid": "-0.0054",
        "pctChange": "-0.09",
        "bid": "5.7276",
        "ask": "5.7282",
        "timestamp": "1618315045",
        "create_date": "2021-04-13 08:57:27"
    },
    "EURBRL": {
        "code": "EUR",
        "codein": "BRL",
        "name": "Euro/Real Brasileiro",
        "high": "6.8327",
        "low": "6.8129",
        "varBid": "-0.0069",
        "pctChange": "-0.1",
        "bid": "6.8195",
        "ask": "6.822",
        "timestamp": "1618315093",
        "create_date": "2021-04-13 08:58:15"
    },
    "BTCBRL": {
        "code": "BTC",
        "codein": "BRL",
        "name": "Bitcoin/Real Brasileiro",
        "high": "360000",
        "low": "340500",
        "varBid": "17072.9",
        "pctChange": "4.98",
        "bid": "359973.9",
        "ask": "359974",
        "timestamp": "1618315092",
        "create_date": "2021-04-13 08:58:12"
    }
}
```

{% endtab %}

{% tab title="404 Moeda especificada não existe" %}

```
{
    "status": 404,
    "code": "CoinNotExists",
    "message": "moeda nao encontrada ABC-BRL"
}
```

{% endtab %}
{% endtabs %}

## Retorna o fechamento dos últimos dias

<mark style="color:blue;">`GET`</mark> `https://economia.awesomeapi.com.br/json/daily/:moeda/:numero_dias`

**<https://economia.awesomeapi.com.br/json/daily/USD-BRL/15>**

#### Path Parameters

| Name         | Type   | Description                                       |
| ------------ | ------ | ------------------------------------------------- |
| moeda        | string | Código da moeda Ex: USD-BRL                       |
| numero\_dias | number | Numero de dias a retornar. (Padrão 1. Máximo 360) |

{% tabs %}
{% tab title="200 " %}

```javascript
[
    {
        varBid: "-0.0143",
        code: "USD",
        codein: "BRL",
        name: "Dólar Americano/Real Brasileiro",
        high: "3.8906",
        low: "3.8596",
        pctChange: "-0.37",
        bid: "3.8659",
        ask: "3.8671",
        timestamp: "1555360543",
        create_date: "2019-04-15 17:35:43"
    },
    {
        varBid: "0.0006",
        high: "3.9076",
        low: "3.8571",
        pctChange: "0.02",
        bid: "3.8808",
        ask: "3.8829",
        timestamp: "1555275600"
    },
    {
        varBid: "0.0248",
        high: "3.9076",
        low: "3.8571",
        pctChange: "0.64",
        bid: "3.8813",
        ask: "3.8823",
        timestamp: "1555102794"
    },
    {
        varBid: "0.0237",
        high: "3.9076",
        low: "3.8571",
        pctChange: "0.62",
        bid: "3.8805",
        ask: "3.881",
        timestamp: "1555102774"
    },
    ...
]
```

{% endtab %}
{% endtabs %}

## Retorna o fechamento de um período específico

<mark style="color:blue;">`GET`</mark> `https://economia.awesomeapi.com.br/json/daily/:moeda/:numero_dias?start_date=20180901&end_date=20180930`

**<https://economia.awesomeapi.com.br/json/daily/USD-BRL/?start\\_date=20180901\\&end\\_date=20180930>**

#### Path Parameters

| Name          | Type   | Description                                       |
| ------------- | ------ | ------------------------------------------------- |
| :moeda        | string | Código da moeda Ex: USD-BRL                       |
| :numero\_dias | number | Numero de dias a retornar. (Padrão 1. Máximo 360) |

#### Query Parameters

| Name        | Type   | Description                                                    |
| ----------- | ------ | -------------------------------------------------------------- |
| start\_date | string | Data de inicio dos resultados no formato YYYYMMDD Ex: 20180901 |
| end\_date   | string | Data limite dos resultados no formato YYYYMMDD Ex: 20180930    |

{% tabs %}
{% tab title="200 " %}

```javascript
[
    {
        code: "USD",
        codein: "BRL",
        name: "Dólar Americano/Real Brasileiro",
        high: "4.0256",
        low: "4.0256",
        pctChange: "0.834",
        bid: "4.0256",
        ask: "4.0276",
        varBid: "0.0333",
        timestamp: "1538136540000",
        create_date: "2018-09-28 06:20:02"
    },
    {
        high: "4.0376",
        low: "4.0376",
        pctChange: "0.313",
        bid: "4.0376",
        ask: "4.0388",
        varBid: "0.0126",
        timestamp: "1538050140000"
    },
    {
        high: "4.0912",
        low: "4.0912",
        pctChange: "0.262",
        bid: "4.0912",
        ask: "4.0937",
        varBid: "0.0107",
        timestamp: "1537963800000"
    },
    {
        high: "4.1094",
        low: "4.1094",
        pctChange: "0.553",
        bid: "4.1094",
        ask: "4.1106",
        varBid: "0.0226",
        timestamp: "1537877400000"
    },
    {
        high: "4.0539",
        low: "4.0539",
        pctChange: "0.183",
        bid: "4.0539",
        ask: "4.0551",
        varBid: "0.0074",
        timestamp: "1537791000000"
    },
    ...
]
```

{% endtab %}
{% endtabs %}

## Retorna cotações sequenciais de uma única moeda (intervalo de 1 minuto)

<mark style="color:blue;">`GET`</mark> `https://economia.awesomeapi.com.br/:moeda/:quantidade`

Retorna valores de uma moeda

**\*Limite para requisições não autenticadas 100.  Autenticadas 1500.**

#### Path Parameters

| Name       | Type   | Description                                                       |
| ---------- | ------ | ----------------------------------------------------------------- |
| moeda      | string | Código da moeda Ex.: USD-BRL                                      |
| quantidade | number | Número de resultados para retornar. (Padrão 1. \*Máximo 100/1500) |

{% tabs %}
{% tab title="200 " %}

```
[
  {
    "code": "USD",
    "codein": "BRL",
    "name": "Dólar Americano/Real Brasileiro",
    "high": "3.6713",
    "low": "3.62",
    "pctChange": "-0.455",
    "bid": "3.6269",
    "ask": "3.6281",
    "varBid": "-0.0166",
    "timestamp": "1527103140000",
    "create_date": "2018-05-23 16:30:02"
  }
]
```

{% endtab %}

{% tab title="404 " %}

```
[
]
```

{% endtab %}
{% endtabs %}

## Retorna cotações sequenciais de um período específico (intervalo de 1 minuto)

<mark style="color:blue;">`GET`</mark> `https://economia.awesomeapi.com.br/:moeda/:quantidade?start_date=20200301&end_date=20200330`

**<https://economia.awesomeapi.com.br/USD-BRL/10?start\\_date=20200201\\&end\\_date=20200229>**

**\*Limite para requisições não autenticadas 100.  Autenticadas 1500.**

#### Path Parameters

| Name        | Type   | Description                                                       |
| ----------- | ------ | ----------------------------------------------------------------- |
| :moeda      | string | Código da moeda ex.: USD-BRL                                      |
| :quantidade | string | Número de resultados para retornar. (Padrão 1. \*Máximo 100/1500) |

#### Query Parameters

| Name        | Type   | Description                                                     |
| ----------- | ------ | --------------------------------------------------------------- |
| start\_date | string | Data de inicio dos resultados no formato YYYYMMDD ex.: 20200201 |
| end\_date   | string | Data limite dos resultados no formato YYYYMMDD ex.: 20200229    |

{% tabs %}
{% tab title="200 " %}

```json
[
    {
        code: "USD",
        codein: "BRL",
        name: "Dólar Americano/Real Brasileiro",
        high: "5.1945",
        low: "5.101",
        varBid: "0.0941",
        pctChange: "1.85",
        bid: "5.1931",
        ask: "5.1945",
        timestamp: "1585601928",
        create_date: "2020-03-30 17:58:48"
    },
    {
        high: "5.1945",
        low: "5.101",
        varBid: "0.0936",
        pctChange: "1.84",
        bid: "5.1926",
        ask: "5.194",
        timestamp: "1585601749"
    },
    {
        high: "5.1945",
        low: "5.101",
        varBid: "0.0933",
        pctChange: "1.83",
        bid: "5.1921",
        ask: "5.194",
        timestamp: "1585601560"
    },
    {
        high: "5.1945",
        low: "5.101",
        varBid: "0.0923",
        pctChange: "1.81",
        bid: "5.1905",
        ask: "5.1936",
        timestamp: "1585601379"
    },
    {
        high: "5.1945",
        low: "5.101",
        varBid: "0.0916",
        pctChange: "1.8",
        bid: "5.1906",
        ask: "5.192",
        timestamp: "1585601199"
    },
    ...
]
```

{% endtab %}
{% endtabs %}

## Formato de resposta

<mark style="color:blue;">`GET`</mark> `https://economia.awesomeapi.com.br/:format/:moeda`

**<https://economia.awesomeapi.com.br/json/USD-BRL>**

#### Path Parameters

| Name   | Type   | Description                     |
| ------ | ------ | ------------------------------- |
| format | string | JSON (default) e XML            |
| moeda  | string | Código da moeda a ser retornada |

{% tabs %}
{% tab title="200 XML Response" %}

```markup
<xml>
    <item>
        <varBid>-0.0119</varBid>
        <code>USD</code>
        <codein>BRL</codein>
        <name>Dólar Americano/Real Brasileiro</name>
        <high>3.8906</high>
        <low>3.8596</low>
        <pctChange>-0.31</pctChange>
        <bid>3.8685</bid>
        <ask>3.8692</ask>
        <timestamp>1555361148</timestamp>
        <create_date>2019-04-15 17:45:49</create_date>
    </item>
</xml>
```

{% endtab %}
{% endtabs %}

#### Exemplos

```
http://economia.awesomeapi.com.br/json/last/USD-BRL
http://economia.awesomeapi.com.br/json/last/USD-BRL,EUR-BRL,BTC-BRL

http://economia.awesomeapi.com.br/xml/USD-BRL/1
http://economia.awesomeapi.com.br/USD-BRL/1?format=xml
```

### Legendas

| **key**      | **Label**                  |
| ------------ | -------------------------- |
| bid          | Compra                     |
| ask          | Venda                      |
| varBid       | Variação                   |
| pctChange    | Porcentagem de Variação    |
| high         | Máximo                     |
| low          | Mínimo                     |
| timestamp    | Hora da negociação (UTC)   |
| create\_date | Hora da negociação (UTC-3) |


# API CEP

Base de CEP IBGE atualizado periódicamente

## Buscar um CEP

<mark style="color:blue;">`GET`</mark> `https://cep.awesomeapi.com.br/:format/:cep`

Retorna o endereço do CEP\
Ex.: **<https://cep.awesomeapi.com.br/json/01001000>**

#### Path Parameters

| Name                                  | Type      | Description                                                      |
| ------------------------------------- | --------- | ---------------------------------------------------------------- |
| format                                | string    | Formato de resposta JSON (padrão), XML                           |
| cep<mark style="color:red;">\*</mark> | string(8) | Apenas os 8 números do CEP com o "0" do inicio exemplo: 01001000 |

{% tabs %}
{% tab title="200 CEP encontrado" %}

```json
{
    "cep": "01001000",
    "address_type": "Praça",
    "address_name": "da Sé",
    "address": "Praça da Sé",
    "state": "SP",
    "district": "Sé",
    "lat": "-23.5502784",
    "lng": "-46.6342179",
    "city": "São Paulo",
    "city_ibge": "3550308",
    "ddd": "11"
}
```

{% endtab %}

{% tab title="400 CEP inválido" %}

```
{
    status: 400,
    code: "invalid",
    message: "CEP invalido"
}
```

{% endtab %}

{% tab title="404 CEP não encontrado" %}

```javascript
{
    status: 404,
    code: "not_found",
    message: "O CEP 00000000 nao foi encontrado"
}
```

{% endtab %}
{% endtabs %}


# API gRPC

Endpoint: grpcs\://cepb.awesomeapi.com.br

<https://github.com/raniellyferreira/awesomeapi-cep/blob/master/proto/address.proto>

<details>

<summary>Proto file</summary>

```protobuf
syntax = "proto3";

package addr.v1;

option go_package = "./;pb";

// -- Services
service AddressService {
    rpc FindByCep (AddressRequest) returns (Address) {}
}

// -- Messages
message Empty {}

message Address {
    string cep = 1;
    string address_type = 2;
    string address_name = 3;
    string address = 4;
    string state = 5;
    string district = 6;
    string lat = 7;
    string lng = 8;
    string city = 9;
    string city_ibge = 10;
    string ddd = 11;
}

message AddressList {
    repeated Address addresses = 1;
}

message AddressRequest {
    string cep = 1;
}
```

</details>


# API Busca de Endereços

Busca de endereços brasileiros por geolocalização ou texto.

Endpoint: <https://cep.awesomeapi.com.br/search>

Preview: [https://addresssearch.awesomeapi.com.br](https://addresssearch.awesomeapi.com.br/)

Esta documentação detalha os novos endpoints de busca, permitindo pesquisas textuais e por Geolocalização + distância em KM.

Permite buscar endereços por termos textuais (logradouro, cidade, estado, etc.) e/ou por proximidade geográfica (latitude e longitude).\
\
**Método:** `GET`\
**URL:** `/search` (e variantes como `/search/:query`)

#### Parâmetros de Consulta (Query Parameters)

| Parâmetro | Tipo   | Descrição                                                                               | Padrão  |
| --------- | ------ | --------------------------------------------------------------------------------------- | ------- |
| `q`       | string | Termo de busca textual. Pode ser passado na URL como `/search/termo`.                   | `*`     |
| `state`   | string | Filtra resultados por UF (ex: SP, RJ).                                                  | -       |
| `lat`     | float  | Latitude para busca por geolocalização. Obrigatório para funcionalidades de distância.  | -       |
| `lng`     | float  | Longitude para busca por geolocalização. Obrigatório para funcionalidades de distância. | -       |
| `d`       | float  | Raio de distância em quilômetros (km) para filtrar resultados. (padrão é sem limite)    | `0.0`\* |
| `sort`    | string | Direção da ordenação por distância (`asc` ou `desc`). Requer `lat` e `lng`.             | `asc`   |
| `limit`   | int    | Número máximo de resultados retornados por página (Máx: 10).                            | `10`    |
| `page`    | int    | Número da página para paginação. (Apenas autenticado)                                   | `1`     |
| `format`  | string | Formato da resposta: `json` ou `xml`.                                                   | `json`  |

\* *O valor padrão de `d` é sem limite sempre que `lat`/`lng` forem fornecidos e `d` for omitido.*

#### Cenários de Uso

**1. Busca Textual Simples**

**Exemplo de Request:**

```http
GET https://cep.awesomeapi.com.br/search?q=paulista
# ou
GET https://cep.awesomeapi.com.br/search/paulista
```

**2. Busca por Geolocalização (Proximidade)**

Busca endereços próximos a uma coordenada específica. Se nenhum raio (`d`) for informado, busca num raio padrão de 1km.

**Exemplo de Request:**

```http
GET https://cep.awesomeapi.com.br/search?lat=-23.56168&lng=-46.65598
```

**3. Busca Combinada (Texto + Geolocalização)**

Busca por termos textuais dentro de um raio específico de uma coordenada, ordenando os resultados pela distância.

**Exemplo de Request:**

```http
GET https://cep.awesomeapi.com.br/search?q=paulista&lat=-23.56168&lng=-46.65598&d=5
```

**4. Filtro por Estado (UF)**

Filtra os resultados para exibir apenas endereços de um estado específico.

**Exemplo de Request:**

```http
GET https://cep.awesomeapi.com.br/search?q=av+paulista&state=SP
```

#### Exemplo de Resposta (JSON)

```json
{
  "results": [
    {
      "cep": "01310-100",
      "address_type": "Avenida",
      "address_name": "Paulista",
      "address": "Avenida Paulista",
      "state": "SP",
      "state_name": "São Paulo",
      "district": "Bela Vista",
      "lat": "-23.561684",
      "lng": "-46.655981",
      "city": "São Paulo",
      "city_ibge": "3550308",
      "ddd": "11",
      "distance_km": 0.010534
    },
    {
      "cep": "01311-200",
      "address_type": "Rua",
      "address_name": "Augusta",
      "address": "Rua Augusta",
      "state": "SP",
      "state_name": "São Paulo",
      "district": "Consolação",
      "lat": "-23.558284",
      "lng": "-46.660981",
      "city": "São Paulo",
      "city_ibge": "3550308",
      "ddd": "11",
      "distance_km": 0.543210
    }
  ]
}
```


# Instruções API Key

### Obtenha sua chave de API

1. **Cadastre-se** no [site da Awesome API](https://awesomeapi.com.br/auth/signup).
2. **Crie uma conta**: Preencha os dados e confirme seu e-mail.
3. **Obtenha a chave**: Acesse a seção de API Keys na sua conta.

Com sua chave, você tem direito a 100 mil requisições mensais gratuitas sem cache.

Para realizar uma solicitação com a chave de API, você pode incluir o token em um dos seguintes lugares:

**Usando Query Parameters**

```plaintext
GET https://economia.awesomeapi.com.br/json/last/{moedas}?token=SEU_API_KEY
```

**Usando Header Parameters**

```plaintext
GET https://economia.awesomeapi.com.br/json/last/{moedas}
Headers:
  x-api-key: SEU_API_KEY
```

#### Query Parameters

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| token | string | API Key     |

#### Header Parameters

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| x-api-key | string | API Key     |