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

# Look up an IP address

> Get the country, city and network of an IPv4 or IPv6 address, and flag hosting and Tor traffic.

### Good to know

* **Country is reliable, city is approximate.** Country-level results are accurate for most addresses. The city is often the network operator's location, which can be far from the user, especially on mobile networks.
* **The data is refreshed daily.** Addresses that recently changed hands may show their previous owner for a day or two.
* **`hosting` means a server, not a person.** The address belongs to a cloud or hosting provider. Real users rarely browse from these, so it often points to a bot, VPN or proxy. Some company VPNs and privacy relays also run on cloud providers.
* **`tor` means the user is anonymous.** The address is a current Tor exit node. The location is the exit node's, not the user's.
* **`reserved: true` usually means the wrong address.** Private and loopback addresses such as `10.0.0.5` are not on the internet. Behind a load balancer, send the client address from `X-Forwarded-For` instead.
* **`data_unavailable` is free.** If the IP data is still loading, the request returns `503` and is not charged. Try again after a few seconds.
* **Credit DB-IP if you show locations.** The geolocation data is licensed under CC BY 4.0. If you display the city, region or country to users, include "IP geolocation by [DB-IP](https://db-ip.com)" near it.

IP geolocation by [DB-IP](https://db-ip.com).

<Card title="Guide: sign-up fraud checks" icon="user-shield" href="/guides/sign-up-fraud-checks">
  Combine the IP lookup with email and phone checks when someone registers.
</Card>


## OpenAPI

````yaml api-reference/openapi.yaml POST /v1/ip/lookup
openapi: 3.1.0
info:
  title: Finowl API
  version: '1.0'
  description: >
    Check emails and passwords against known data breaches, predict gender from
    names

    and emails, check cold-email compliance, validate email addresses and phone
    numbers,

    look up companies by domain and geolocate IP addresses. Every endpoint is a
    JSON

    `POST` authenticated with a bearer API key.
servers:
  - url: https://api.finowl.co
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Breaches
    description: Check whether an email or password appears in known data breaches.
  - name: Gender
    description: Predict gender from a name or email, one at a time or in batches.
  - name: Compliance
    description: >-
      Place an email address in a jurisdiction and return that jurisdiction's
      cold-email rule.
  - name: Email validation
    description: >-
      Check whether an email address can receive mail, and catch typos,
      disposable and role addresses.
  - name: Company
    description: Look up public company details from a domain or work email.
  - name: IP
    description: Geolocate an IP address and flag hosting, proxy and Tor traffic.
  - name: Phone
    description: Validate, format and classify a phone number.
paths:
  /v1/ip/lookup:
    post:
      tags:
        - IP
      summary: Look up an IP address
      description: >
        Returns the country, region, city and network (ASN) of an IPv4 or IPv6
        address, and flags

        addresses that belong to cloud and hosting providers or are current Tor
        exit nodes.


        The lookup runs in memory on Finowl's own infrastructure against data
        refreshed daily:

        IP geolocation by [DB-IP](https://db-ip.com) (CC BY 4.0), the IP ranges
        that cloud

        providers publish, and the public Tor exit list. Nothing is called per
        request.


        Private, loopback and other reserved addresses return `reserved: true`
        with empty

        location and network fields.


        Costs **1 credit**. A `503` where the lookup could not complete is not
        charged.
      operationId: lookupIp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - ip
              properties:
                ip:
                  type: string
                  maxLength: 64
                  description: >-
                    An IPv4 or IPv6 address, such as `8.8.8.8` or
                    `2001:4860:4860::8888`. Ranges (CIDR), hostnames, ports and
                    IPv6 zones such as `fe80::1%eth0` return `invalid_input`.
                  example: 8.8.8.8
            examples:
              hosting:
                summary: Cloud address
                value:
                  ip: 8.8.8.8
              residential:
                summary: Residential address
                value:
                  ip: 81.2.69.160
              ipv6:
                summary: IPv6
                value:
                  ip: 2a02:c7c:a0e3:7600::1
              reserved:
                summary: Private address
                value:
                  ip: 192.168.1.20
      responses:
        '200':
          description: The lookup completed. Unknown fields are empty or `null`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpLookupResult'
              examples:
                hosting:
                  summary: Cloud address
                  value:
                    ip: 8.8.8.8
                    version: 4
                    country_code: US
                    country: United States
                    region: California
                    city: Mountain View
                    asn: 15169
                    as_name: Google LLC
                    hosting: true
                    hosting_provider: google_cloud
                    tor: false
                    reserved: false
                residential:
                  summary: Residential address
                  value:
                    ip: 81.2.69.160
                    version: 4
                    country_code: GB
                    country: United Kingdom
                    region: England
                    city: London
                    asn: 20712
                    as_name: Andrews & Arnold Ltd
                    hosting: false
                    hosting_provider: null
                    tor: false
                    reserved: false
                tor:
                  summary: Tor exit node
                  value:
                    ip: 185.220.101.4
                    version: 4
                    country_code: DE
                    country: Germany
                    region: Brandenburg
                    city: Brandenburg an der Havel
                    asn: 60729
                    as_name: Stiftung Erneuerbare Freiheit
                    hosting: false
                    hosting_provider: null
                    tor: true
                    reserved: false
                reserved:
                  summary: Private address
                  value:
                    ip: 192.168.1.20
                    version: 4
                    country_code: ''
                    country: ''
                    region: null
                    city: null
                    asn: null
                    as_name: null
                    hosting: false
                    hosting_provider: null
                    tor: false
                    reserved: true
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: >-
            `data_unavailable`: the IP data is still loading, for example just
            after a restart. Not charged. Retry after a short delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: data_unavailable
        '504':
          $ref: '#/components/responses/Unconfirmed'
components:
  schemas:
    IpLookupResult:
      type: object
      required:
        - ip
        - version
        - country_code
        - country
        - region
        - city
        - asn
        - as_name
        - hosting
        - hosting_provider
        - tor
        - reserved
      properties:
        ip:
          type: string
          description: >-
            The address in canonical form, for example IPv6 compressed and
            lowercased.
        version:
          type: integer
          enum:
            - 4
            - 6
          description: The IP version.
        country_code:
          type: string
          description: >-
            ISO 3166-1 alpha-2 code of the country the address is registered to
            or used in. Empty when unknown or `reserved`.
        country:
          type: string
          description: The country name for `country_code`. Empty when unknown.
        region:
          type:
            - string
            - 'null'
          description: >-
            The state, province or region, such as `California`. `null` when
            unknown.
        city:
          type:
            - string
            - 'null'
          description: >-
            The nearest city. Often the location of the network operator rather
            than the user, especially for mobile networks. `null` when unknown.
        asn:
          type:
            - integer
            - 'null'
          description: >-
            The autonomous system number of the network that announces the
            address. `null` when unknown.
        as_name:
          type:
            - string
            - 'null'
          description: >-
            The name of that network's operator, such as `Google LLC` or an
            internet provider. `null` when unknown.
        hosting:
          type: boolean
          description: >-
            `true` when the address is in a range published by a cloud provider
            or belongs to a known hosting network. Real users rarely browse from
            these addresses, so it often indicates a server, VPN or proxy.
        hosting_provider:
          type:
            - string
            - 'null'
          enum:
            - aws
            - google_cloud
            - azure
            - cloudflare
            - oracle_cloud
            - digitalocean
            - linode
            - vultr
            - hetzner
            - ovh
            - other_hosting
            - null
          description: >-
            The hosting provider when `hosting` is `true`, `other_hosting` for
            any other hosting network, `null` otherwise. Treat values you don't
            recognize like `other_hosting`.
        tor:
          type: boolean
          description: >-
            `true` when the address is a current Tor exit node, so the real user
            is anonymous.
        reserved:
          type: boolean
          description: >-
            `true` for private, loopback, link-local, carrier-grade NAT,
            documentation and other reserved addresses. These are not on the
            public internet, so all location and network fields are empty,
            `null` or `false`. Usually it means you sent your proxy's address
            instead of the client's.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
          properties:
            code:
              type: string
              description: >-
                A stable, machine-readable error code. See the Errors page for
                the full list.
              example: invalid_input
  responses:
    InvalidInput:
      description: The request body is not valid. Fix the request before trying again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_input
    Unauthorized:
      description: The API key is missing, malformed or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
    TooManyRequests:
      description: >
        `rate_limited` (too many requests this minute), `quota_exceeded` (not
        enough credits) or

        `provider_rate_limited` (Finowl intelligence is busy). Check the
        `Retry-After` header.
      headers:
        Retry-After:
          description: Seconds to wait before trying again.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
    Unconfirmed:
      description: >-
        The lookup did not finish in time. It may or may not have run, and the
        request was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_response_unconfirmed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your Finowl API key, for example `finowl_3f9a...`. Create keys in the
        dashboard under **API Keys**.

````

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