> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK location service

> Use the AvraAPI Node.js SDK to resolve a permitted IPv4 or IPv6 address.

Use `avraapi.location()` to resolve one permitted IP address. The Location
service has one released async operation and returns `Promise<ApiResponse<GeoIpData>>`.

<Note>
  Use `avraapi.location().withPrivacyMode().lookupIp({ ip: 'IP_ADDRESS' })`
  for the shared one-request privacy control. The existing `privacyMode: true`
  input remains supported and sends the same `X-Privacy-Mode: 1` header.
</Note>

## Look up an IP address

`lookupIp({ ip, privacyMode? })` accepts IPv4 or IPv6 text. Prefer the fluent
`withPrivacyMode()` style when a consistent one-request control is clearer.

**SDK function**

```ts title="Copy the SDK call" theme={null}
const response = await avraapi.location()
  .withPrivacyMode()
  .lookupIp({ ip: 'IP_ADDRESS' });
```

| Field | Use |
| - | - |
| `ip` | Permitted IPv4 or IPv6 address. |
| `privacyMode` | Optional convenience input; `true` sends `X-Privacy-Mode: 1`. |

```ts title="Resolve an IP address with the shared privacy control" theme={null}
// AvraAPI SDK call.
const response = await avraapi.location()
  .withPrivacyMode()
  .lookupIp({ ip: '8.8.8.8' });

// Your application code.
const location = {
  country: response.data.country,
  city: response.data.city,
  timezone: response.data.timezone,
  coordinates: {
    latitude: response.data.latitude,
    longitude: response.data.longitude,
  },
};
const requestId = response.requestId;
```

### Response

```json theme={null}
{
  "success": true,
  "request_id": "67257c6b-c48f-42f6-9d96-0224c504c30b",
  "data": {
    "country": "Sri Lanka",
    "country_code": "LK",
    "city": "Colombo",
    "isp": "Starlink IPv4 Customer Space",
    "latitude": 6.9394,
    "longitude": 79.8476,
    "timezone": "Asia/Colombo"
  },
  "meta": {"provider_override": null}
}
```

Provider fields can be `null` when no matching data is available. Privacy Mode
does not anonymise the request; see the [REST API guide](/api-reference/rest-api#x-privacy-mode)
for the privacy guarantee.

## Select a configured provider for one request

Every Node.js provider service inherits `withProvider(providerCode)`. It sends
`X-Provider-Override` for the next request only, then clears. Use it only for a
provider configured in the selected project environment.

```ts title="Optional provider selection" theme={null}
// AvraAPI SDK call. The override affects this lookup only.
const response = await avraapi.location()
  .withProvider('maxmind')
  .lookupIp({ ip: '2001:4860:4860::8888' });

// Your application code.
const providerHint = response.meta.provider_override;
```

`meta.provider_override` reports the requested hint. It does not guarantee
that every returned field originated from that provider.

## Use the result safely

Keep Location calls in your backend and process only IP addresses you are
permitted to use. Do not treat country, city, network, or coordinate fields as
identity proof. The [Location REST API Reference](/api-reference/location/lookup)
contains the full request, field, and error contract.

For SDK failures, follow [Node.js Overview and setup](/sdk/nodejs/overview-and-setup#handle-errors-safely)
and retain the request ID only in backend support records.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.