> ## 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.

# PHP SDK location service

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

Use `$avraapi->location()` to resolve one permitted IP address. The Location
service has one released operation and returns an `ApiResponse`.

<Note>
  Use `$avraapi->location()->withPrivacyMode()->lookupIp('IP_ADDRESS')` for
  the shared one-request privacy control. It sends `X-Privacy-Mode: 1` only
  for that next request, then clears automatically. Privacy Mode keeps normal
  routing, billing, and usage tracking while suppressing request and response
  payload storage. The existing `privacyMode: true` argument remains supported.
</Note>

## Look up an IP address

`lookupIp(string $ip, bool $privacyMode = false): ApiResponse` accepts IPv4 or
IPv6 text. The optional `privacyMode: true` argument remains available; for a
consistent fluent style, use `withPrivacyMode()` immediately before the call.

**SDK function**

```php title="Copy the SDK call" theme={null}
$response = $avraapi->location()
    ->withPrivacyMode()
    ->lookupIp(ip: 'IP_ADDRESS');
```

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

```php title="Resolve an IP address with the shared privacy control" theme={null}
<?php

// AvraAPI SDK call.
$response = $avraapi->location()
    ->withPrivacyMode()
    ->lookupIp(ip: '8.8.8.8');

// Your application code.
$location = [
    'country' => $response->data['country'],
    'city' => $response->data['city'],
    'timezone' => $response->data['timezone'],
    'coordinates' => [
        'latitude' => $response->data['latitude'],
        'longitude' => $response->data['longitude'],
    ],
];
$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
  }
}
```

Every result field can be `null` when the selected provider has no matching
data. Privacy mode preserves normal routing, billing, and usage tracking while
suppressing request and response payload storage. It does not anonymise the
request. See the [REST API guide](/api-reference/rest-api#x-privacy-mode) for
the shared privacy guarantee.

## Select a configured provider for one request

Every PHP provider service inherits
`withProvider(string $providerCode): static`. It sets an `X-Provider-Override`
header for the next request only, then the SDK clears the override. Use it only
with a provider that is configured for the selected project environment.

```php title="Optional provider selection" theme={null}
<?php

// AvraAPI SDK call. The override affects this lookup only.
$response = $avraapi->location()
    ->withProvider('maxmind')
    ->lookupIp('2001:4860:4860::8888');

// Your application code.
$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, use the typed exception pattern in
[PHP Overview and setup](/sdk/php/overview-and-setup#handle-errors-safely) and
retain the exception request ID for support.


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