Skip to content
locate-me v0.1.0
Checking

ReferenceBulk Lookup

Bulk Lookup

Locates up to 100 addresses in one request. Results come back in request order, with an error in place of each address that could not be located.

  • API key
  • 1 unit per address
POST/v1/lookup

Request

ParameterInDescription
ipsbodyArray of 1 to limits.bulk_max_ips (100) address strings. Other fields are rejected.
langqueryLanguage of place names, as for Lookup.
Content-TypeheaderMust be application/json.
curl -H "X-API-Key: $LOCATE_ME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["1.1.1.1", "192.168.0.1", "bogus"]}' \
  http://localhost:8080/v1/lookup

The request body may be at most server.max_body_bytes (256 KiB).

Response

200 OK
{
  "results": [
    {
      "ip": "1.1.1.1",
      "network": "1.1.1.0/24",
      "continent": { "code": "OC", "name": "Oceania" },
      "country": { "code": "AU", "name": "Australia", "in_eu": false },
      "region": { "name": "New South Wales" },
      "city": "Sydney",
      "location": { "latitude": -33.8688, "longitude": 151.209 }
    },
    { "ip": "192.168.0.1", "error": "reserved_address" },
    { "ip": "bogus", "error": "invalid_ip" }
  ]
}

Each entry of results is either a location, shaped exactly like a Lookup response, or an {"ip", "error"} pair. Tell them apart by the presence of error. In an error pair, ip repeats the string as you sent it.

Entry errorMeaning
invalid_ipNot a valid IPv4 or IPv6 address.
reserved_addressA private or reserved range, which never has a location.
not_foundThe database has no location for the address.

Cost

Every address costs one rate-limit unit, invalid ones included. One unit is charged before the body is read, so malformed requests are not free; the rest is charged once the batch size is known.

  • A batch larger than the key's burst can never be admitted. It fails at once with 429 exceeds_burst; split it.
  • A batch that fits the burst but not the units left fails with 429 rate_limited and a Retry-After.

Errors

StatusCodeWhen
400invalid_bodyThe body is not {"ips": [...]}: bad JSON, a wrong type or an unknown field.
400invalid_langlang is not supported.
401unauthorizedMissing, unknown or disabled key.
413payload_too_largeThe body is larger than server.max_body_bytes.
415unsupported_media_typeContent-Type is not application/json.
422empty_batchips is empty.
422batch_too_largeMore than limits.bulk_max_ips addresses.
429exceeds_burstThe batch costs more than the key's burst.
429rate_limitedNot enough units left; wait Retry-After seconds.
Esc