Endpoints

Endpoints

Parâmetros

Parameters

Exemplo

Example

curl https://api.alicercelabs.com.br/api/v1/ip/8.8.8.8 \
          -H "Authorization: Bearer <token>"

{
          "success": true,
          "data": {
            "ip": "8.8.8.8",
            "version": 4,
            "scope": "public",
            "routable": true,
            "location": {
              "country": { "code": "US", "name": "United States", "is_eu": false },
              "region": { "code": "", "name": "California" },
              "city": "Mountain View",
              "latitude": 37.422,
              "longitude": -122.085,
              "timezone": "America/Los_Angeles"
            },
            "network": {
              "cidr": "8.8.8.0/24",
              "asn": 15169,
              "asn_name": "GOOGLE",
              "organization": "Google LLC",
              "rir": "ARIN",
              "cloud": null
            },
            "privacy": {
              "anonymous": false,
              "vpn": { "detected": false, "confidence": "medium" },
              "tor": { "detected": false, "exit_node": false }
            },
            "traits": { "hosting": null, "datacenter": null, "bogon": false }
          },
          "meta": { "elapsed_ms": 5, "request_id": "..." }
        }

Um IP privado/reservado não é erro. É um endereço válido, só não roteável publicamente. GET /api/v1/ip/192.168.1.10 responde 200 com scope: "private", routable: false, e location/network como null. 400 é reservado pra entrada que não é sequer um endereço IP literal.

A private/reserved IP is not an error. It's a valid address, just not publicly routable. GET /api/v1/ip/192.168.1.10 returns 200 with scope: "private", routable: false, and location/network as null. 400 is reserved for input that isn't even a literal IP address.

curl https://api.alicercelabs.com.br/api/v1/ip/self/ip
8.8.8.8

/self/ip devolve só o endereço, sem token exigido. É o que a conexão de fato usou (IPv4 ou IPv6), não força uma família: pra isso, script/curl é o uso normal.

/self/ip returns just the address, no token required. It reports whatever the connection actually used (IPv4 or IPv6), never forces a family: this is meant for scripts and curl.

Erros possíveis

Possible errors

Quando uma categoria não tem sinal disponível pro IP consultado, o campo correspondente vem null. Nunca um erro 500.

When a category has no signal available for the queried IP, the corresponding field comes back null. Never a 500.

Limitações da geolocalização

Geolocation limitations

Geolocalização por IP é sempre aproximada, nunca um endereço exato:

IP geolocation is always approximate, never an exact address:

• Coordenadas apontam pra uma área provável, não pro endereço residencial de ninguém.
• Coordinates point to a likely area, not anyone's residential address.
• A cidade pode estar errada, principalmente fora de capitais/grandes centros.
• City can be wrong, especially outside capitals/major metro areas.
• Em redes móveis e atrás de CGNAT, o IP reflete o ponto de saída da operadora pra internet, não a localização do aparelho.
• On mobile networks and behind CGNAT, the IP reflects the carrier's internet egress point, not the device's location.
• VPN, proxy ou Tor mudam a localização aparente. É esperado, não um bug do dado.
• VPN, proxy or Tor change the apparent location. That's expected, not a data bug.
• Endereços anycast (comuns em CDN/DNS público) podem legitimamente responder de vários locais físicos simultâneos.
• Anycast addresses (common on CDNs/public DNS) can legitimately answer from several physical locations at once.

Usando o SDK

Using the SDK

SDKs oficiais: Go · Python · JavaScript.

Official SDKs: Go · Python · JavaScript.

Resolver um IP

Resolve an IP

import (
	"context"
	"fmt"

	alicercelabs "github.com/alicercelabs/alicercesdk-go"
)

client := alicercelabs.New("alk_...")
ctx := context.Background()

res, err := client.IP.Lookup(ctx, "8.8.8.8", nil)
if err != nil {
	panic(err)
}
fmt.Println(res.Scope, res.Location.Country.Name, res.Network.Organization)

from alicercelabs import AlicerceLabs

client = AlicerceLabs(api_key="alk_...")

res = client.ip.lookup("8.8.8.8")
print(res["scope"], res["location"]["country"]["name"], res["network"]["organization"])

import { AlicerceLabs } from "alicercesdk-javascript";

const client = new AlicerceLabs("alk_...");

const res = await client.ip.lookup("8.8.8.8");
console.log(res.scope, res.location?.country?.name, res.network?.organization);

Resolver quem está chamando

Resolve the caller

res, err := client.IP.Self(ctx, nil)
fmt.Println(res.IP, res.Scope)

res = client.ip.self()
print(res["ip"], res["scope"])

const res = await client.ip.self();
console.log(res.ip, res.scope);

Resolver vários IPs numa chamada

Resolve several IPs in one call

results, err := client.IP.Batch(ctx, []string{"8.8.8.8", "1.1.1.1"}, nil)
for _, r := range results {
	if r.Success {
		fmt.Println(r.IP, r.Data.Scope)
	}
}

results = client.ip.batch(["8.8.8.8", "1.1.1.1"])
for r in results:
    if r["success"]:
        print(r["ip"], r["data"]["scope"])

const results = await client.ip.batch(["8.8.8.8", "1.1.1.1"]);
for (const r of results) {
  if (r.success) console.log(r.ip, r.data?.scope);
}

Limites

Limits

100/dia · 4/hora sem token, por IP chamador; com uma API key (gerada no painel), 1.000/dia · 41/hora, por operação (lookup, self, batch têm cotas independentes). Sem cache de resposta: os datasets locais já respondem em microssegundos, então cada chamada resolve ao vivo.

100/day · 4/hour without a token, per calling IP; with an API key (generated in the panel), 1,000/day · 41/hour, per operation (lookup, self, batch have independent quotas). No response caching: local datasets already answer in microseconds, so every call resolves live.