Look up an IP address

curl --request POST \
  --url https://avraapi.com/api/v1/location/lookup \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-SECRET: <api-key>' \
  --data '
{
  "ip": "203.0.113.10"
}
'

{
  "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
  }
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "unauthorized",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "insufficient_funds",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "rate_limit_exceeded",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "internal_error",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "project_paused",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

POST

location

lookup

curl --request POST \
  --url https://avraapi.com/api/v1/location/lookup \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-SECRET: <api-key>' \
  --data '
{
  "ip": "203.0.113.10"
}
'

{
  "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
  }
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "unauthorized",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "insufficient_funds",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "rate_limit_exceeded",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "internal_error",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

{
  "success": false,
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": {
    "code": "project_paused",
    "message": "<string>",
    "details": {}
  },
  "meta": {}
}

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

POST

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.

curl

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

{
  "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 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.

Authorizations

X-API-KEY

string

header

required

Your Development project's Client ID. Enter your own value in the Documentation Playground.

X-API-SECRET

string

header

required

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.

Headers

X-ENV

enum<string>

default:development

Selects the Development credential environment. The Documentation Playground exposes Development values only; normal backend integrations may use their documented Production credentials outside this tool.

Available options:

dev,

development

string

Requests a JSON response where the selected operation supports JSON.

Example:

"application/json"

X-Privacy-Mode

boolean

default:false

Optional privacy override. Turn this on to request that AvraAPI suppress request-payload storage in observability logs for this request.

Example:

true

Body

application/json

string<ip>

required

A valid IPv4 or IPv6 address without leading or trailing whitespace.

Example:

"203.0.113.10"

provider

string | null

Optional provider hint. Omit it to use the project's primary enabled Location provider. maxmind is the currently supported explicit value.

Maximum string length: 50

Pattern: ^[A-Za-z0-9_-]+$

Example:

"maxmind"

Response

Location result. Every field in data is present and may be null.

success

enum<boolean>

required

Available options:

true

request_id

string<uuid>

required

Include this value when contacting AvraAPI support.

data

object

required

Operation-specific result data.

Show child attributes

Introduction

Currencies

SMS

Security

Location

Utilities

Look up an IP address

API endpoint

Request fields

Result fields

Request example

Response example

Error codes

Playground resources

Authorizations

Headers

Body

Response

​API endpoint

​Request fields

​Result fields

​Request example

​Response example

​Error codes

​Playground resources

Authorizations

Headers

Body

Response

API endpoint

Request fields

Result fields

Request example

Response example

Error codes

Playground resources