> ## 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.
# Look up an IP address
> Resolve one permitted IPv4 or IPv6 address into the AvraAPI Location result.
Send a JSON body containing one IPv4 or IPv6 address. The response always includes the seven documented `data` fields, but any individual value can be `null` when the selected provider has no matching information.
**Live Testing Guide:** Before using **Try it**, create a Development project, then enter its **Client ID** and **Client Secret**. Configure the relevant provider for that project before sending the request.
## API endpoint
```text title="POST" theme={null}
https://avraapi.com/api/v1/location/lookup
```
## Request fields
| Field | Required | Rules |
| - | - | - |
| `ip` | Yes | Valid IPv4 or IPv6 text. Do not include leading or trailing whitespace. |
| `provider` | No | Optional provider hint. Omit it to use the project's primary enabled Location integration. `maxmind` is the currently supported explicit value. |
Outside the documentation Playground, do not use a raw client-side IP collection flow just to call this API from a browser. Keep the API secret on your backend and send the lookup from there.
## Result fields
| Field | Type | Notes |
| - | - | - |
| `country` | string or `null` | Provider-reported country name. |
| `country_code` | string or `null` | Provider-reported country code. |
| `city` | string or `null` | Provider-reported city name. |
| `isp` | string or `null` | Provider-reported ISP name. |
| `latitude` | number or `null` | Provider-reported latitude. |
| `longitude` | number or `null` | Provider-reported longitude. |
| `timezone` | string or `null` | Provider-reported timezone name. |
`meta.provider_override` mirrors the optional `provider` hint sent in the request. It is not a guarantee that a particular provider produced every field.
## Request example
This example uses IPv4. The same `ip` field also accepts a valid IPv6 address, such as `2001:4860:4860::8888`.
```bash curl theme={null} theme={null}
curl --request POST "https://avraapi.com/api/v1/location/lookup" \
--header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
--header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
--header "X-ENV: development" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{"ip":"8.8.8.8"}'
```
Use only an IP address that you are permitted to process. Provider data is address-dependent, so an IPv4 or IPv6 lookup can legitimately return `null` for one or more result fields.
## Response example
```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
}
}
```
## Error codes
| HTTP | `error.code` | When it happens | What to do |
| - | - | - | - |
| `401` | unauthorized | Credentials are missing, invalid, inactive, or do not match the selected environment. | Check your backend secret configuration and `X-ENV`. |
| `402` | insufficient\_funds | The selected Location integration requires credits that are unavailable. | Check the project's current service configuration and balance. |
| `422` | validation\_failed | `ip` is missing or is not valid IPv4/IPv6 text, or `provider` does not satisfy its input rules. The response includes field details. | Correct the request fields and submit a new request. |
| `422` | provider\_selection\_failed | The requested provider is unavailable for the project environment. | Omit the provider hint or enable/configure the provider. |
| `429` | rate\_limit\_exceeded | The configured request limit was reached. | Respect `Retry-After` when present; do not retry in a tight loop. |
| `500` | internal\_error | The Location service could not complete the request. | Retry only if your workflow permits it, retaining the request ID. |
| `503` | project\_paused | The project is paused. | Reactivate the project before retrying. |
Keep the JSON `request_id` or `X-APIX-Request-ID` response header with your support record. It is the safest way for AvraAPI support to trace a request without asking for the original IP address.
See the [REST API guide](/api-reference/rest-api) for shared credential, privacy, and error-handling guidance.
## Playground resources
The generated reference below lists this endpoint's API standard details: request fields, authorizations, and response schema. The complete integration guide, request and response examples, and endpoint-specific error handling are above.
## OpenAPI
````yaml api-reference/provider-api.openapi.yaml POST /location/lookup
openapi: 3.0.3
info:
title: AvraAPI Provider API
version: 1.0.0
description: >-
The reviewed public contract for AvraAPI provider services. Operations are
added to this document only after their route, validation, response,
privacy, usage, and public-safety contracts have been verified.
servers:
- url: https://avraapi.com/api/v1
description: AvraAPI REST API v1
security:
- ApiKeyHeader: []
ApiSecretHeader: []
tags:
- name: Currency
description: Currency codes, exchange rates, and conversion.
- name: SMS
description: Messaging operations through configured AvraAPI providers.
- name: Security
description: IP and email security checks.
- name: Location
description: IP geolocation and intelligence.
- name: Utilities
description: QR code, barcode, and PDF generation.
paths:
/location/lookup:
post:
tags:
- Location
summary: Look up an IPv4 or IPv6 address
description: >-
Resolves a permitted IPv4 or IPv6 address through the Location service.
The response uses a stable AvraAPI envelope and can contain null values
when the selected provider has no value for a field. The current managed
provider is MaxMind GeoLite2; provider availability remains project and
environment specific.
operationId: locationLookup
parameters:
- $ref: '#/components/parameters/XEnvironmentHeader'
- $ref: '#/components/parameters/AcceptJsonHeader'
- $ref: '#/components/parameters/XPrivacyModeHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LocationLookupRequest'
examples:
documentation_test_network:
summary: Documentation-only TEST-NET address
value:
ip: 203.0.113.10
explicit_provider:
summary: Explicitly select the currently supported provider
value:
ip: 2001:db8::10
provider: maxmind
responses:
'200':
description: Location result. Every field in `data` is present and may be null.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/LocationLookupResponse'
examples:
no_matching_record:
summary: A valid address with no available provider record
value:
success: true
request_id: 01f00000-0000-4000-8000-000000000008
data:
country: null
country_code: null
city: null
isp: null
latitude: null
longitude: null
timezone: null
meta:
provider_override: null
'401':
description: >-
Missing, invalid, inactive, or environment-mismatched project
credentials.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/LocationUnauthorizedErrorEnvelope'
examples:
unauthorized:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: unauthorized
message:
details: {}
meta: {}
'402':
description: >-
The selected Location integration requires credits that are
unavailable.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/LocationInsufficientFundsErrorEnvelope'
examples:
insufficient_funds:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: insufficient_funds
message:
details: {}
meta: {}
'422':
description: >-
Invalid request fields. See the Error codes table for the separate
provider-selection outcome.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/LocationValidationErrorEnvelope'
examples:
validation_failed:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: validation_failed
message:
details: {}
meta: {}
'429':
description: The configured Location request limit has been reached.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
Retry-After:
$ref: '#/components/headers/RetryAfterHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/LocationRateLimitedErrorEnvelope'
examples:
rate_limit_exceeded:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: rate_limit_exceeded
message:
details: {}
meta: {}
'500':
description: The Location service could not complete the request.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/LocationInternalErrorEnvelope'
examples:
internal_error:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: internal_error
message:
details: {}
meta: {}
'503':
description: The project is paused and cannot make API requests.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/LocationProjectPausedErrorEnvelope'
examples:
project_paused:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: project_paused
message:
details: {}
meta: {}
components:
parameters:
XEnvironmentHeader:
name: X-ENV
in: header
required: false
description: >-
Selects the Development credential environment. The Documentation
Playground exposes Development values only; normal backend integrations
may use their documented Production credentials outside this tool.
schema:
type: string
enum:
- dev
- development
default: development
AcceptJsonHeader:
name: Accept
in: header
required: false
description: Requests a JSON response where the selected operation supports JSON.
schema:
type: string
example: application/json
XPrivacyModeHeader:
name: X-Privacy-Mode
in: header
required: false
description: >-
Optional privacy override. Turn this on to request that AvraAPI suppress
request-payload storage in observability logs for this request.
schema:
type: boolean
default: false
example: true
schemas:
LocationLookupRequest:
type: object
required:
- ip
properties:
ip:
type: string
format: ip
description: A valid IPv4 or IPv6 address without leading or trailing whitespace.
example: 203.0.113.10
provider:
type: string
nullable: true
maxLength: 50
pattern: ^[A-Za-z0-9_-]+$
description: >-
Optional provider hint. Omit it to use the project's primary enabled
Location provider. `maxmind` is the currently supported explicit
value.
example: maxmind
LocationLookupResponse:
allOf:
- $ref: '#/components/schemas/GatewaySuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/LocationLookupData'
LocationUnauthorizedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- unauthorized
example: unauthorized
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
LocationInsufficientFundsErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- insufficient_funds
example: insufficient_funds
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
LocationValidationErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- validation_failed
example: validation_failed
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
LocationRateLimitedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- rate_limit_exceeded
example: rate_limit_exceeded
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
LocationInternalErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- internal_error
example: internal_error
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
LocationProjectPausedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- project_paused
example: project_paused
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
GatewaySuccessEnvelope:
allOf:
- $ref: '#/components/schemas/ApiSuccessEnvelope'
- type: object
required:
- meta
properties:
meta:
$ref: '#/components/schemas/GatewayResponseMeta'
LocationLookupData:
type: object
required:
- country
- country_code
- city
- isp
- latitude
- longitude
- timezone
properties:
country:
type: string
nullable: true
description: Provider-reported country name, when available.
country_code:
type: string
nullable: true
description: Provider-reported country code, when available.
city:
type: string
nullable: true
description: Provider-reported city name, when available.
isp:
type: string
nullable: true
description: Provider-reported ISP name, when available.
latitude:
type: number
format: double
nullable: true
description: Provider-reported latitude, when available.
longitude:
type: number
format: double
nullable: true
description: Provider-reported longitude, when available.
timezone:
type: string
nullable: true
description: Provider-reported timezone name, when available.
ApiSuccessEnvelope:
type: object
required:
- success
- request_id
- data
properties:
success:
type: boolean
enum:
- true
request_id:
type: string
format: uuid
description: Include this value when contacting AvraAPI support.
data:
description: Operation-specific result data.
nullable: true
GatewayResponseMeta:
type: object
required:
- provider_override
properties:
provider_override:
type: string
nullable: true
description: >-
The optional provider hint supplied by the caller, after gateway
normalisation.
headers:
RequestIdHeader:
description: AvraAPI request identifier for support and troubleshooting.
schema:
type: string
format: uuid
RetryAfterHeader:
description: Seconds to wait before retrying a rate-limited request.
schema:
type: integer
minimum: 0
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: X-API-KEY
description: >-
Your Development project's Client ID. Enter your own value in the
Documentation Playground.
ApiSecretHeader:
type: apiKey
in: header
name: X-API-SECRET
description: >-
Your Development project's Client Secret. Mintlify does not proxy these
requests; the browser sends them directly to AvraAPI. Never enter a
Production secret in the Documentation Playground.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.