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

# IP Geolocation

> Get the city, region, country, latitude and longitude, and time zone of any IPv4 or IPv6 address.

### 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.
* **Coordinates are a point in the city, not the user.** Use them to place a pin or pick a nearby region, not to find a street address.
* **`location.timezone` comes from the coordinates.** It is the time zone of the nearest large city in the same country, or the country's only time zone when the city is unknown. `local_time` is the time there when you made the request.
* **The data is refreshed daily.** Addresses that recently changed hands may show their previous location for a day or two.
* **`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.
* **Need to know if the address can be trusted?** [IP Intelligence](/api-reference/ip/intelligence) adds the network, VPN, Tor, hosting and relay flags and a risk score, for the same 1 credit.

IP geolocation by [DB-IP](https://db-ip.com) (CC BY 4.0). Time zones from [GeoNames](https://www.geonames.org) (CC BY 4.0).


## OpenAPI

````yaml api-reference/openapi.yaml POST /v1/ip/geolocation
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, validate email addresses and phone numbers, look up companies by
    domain,

    and geolocate and assess 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: 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 VPN, Tor, hosting and relay traffic.
  - name: Phone
    description: Validate, format and classify a phone number.
paths:
  /v1/ip/geolocation:
    post:
      tags:
        - IP
      summary: Get IP geolocation
      description: >
        Returns where an IPv4 or IPv6 address is: country, region, city,
        latitude and longitude,

        time zone and local time, and details of the country such as continent
        and currency.


        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) and time zones
        from

        [GeoNames](https://www.geonames.org) (CC BY 4.0). Nothing is called per
        request.


        For the network, VPN, Tor, hosting and risk signals as well, use

        [IP Intelligence](/api-reference/ip/intelligence) instead.


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

        location fields.


        Costs **1 credit**. A `503` where the lookup could not complete is not
        charged.
      operationId: ipGeolocation
      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: Google DNS
                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/IpGeolocationResult'
              examples:
                hosting:
                  summary: Google DNS
                  value:
                    ip: 8.8.8.8
                    version: 4
                    country_code: US
                    country: United States
                    region: California
                    city: Mountain View
                    reserved: false
                    location:
                      latitude: 37.422
                      longitude: -122.085
                      timezone: America/Los_Angeles
                      local_time: '2026-10-15T10:27:05-07:00'
                      utc_offset: '-07:00'
                    country_info:
                      code: US
                      name: United States
                      flag: 🇺🇸
                      continent: North America
                      currency: USD
                      language: en
                      in_eu: false
                      calling_code: 1
                residential:
                  summary: Residential address
                  value:
                    ip: 81.2.69.160
                    version: 4
                    country_code: GB
                    country: United Kingdom
                    region: England
                    city: London
                    reserved: false
                    location:
                      latitude: 51.5143
                      longitude: -0.0912
                      timezone: Europe/London
                      local_time: '2026-10-15T18:27:05+01:00'
                      utc_offset: '+01:00'
                    country_info:
                      code: GB
                      name: United Kingdom
                      flag: 🇬🇧
                      continent: Europe
                      currency: GBP
                      language: en
                      in_eu: false
                      calling_code: 44
                tor:
                  summary: Hamburg, Germany
                  value:
                    ip: 185.220.101.4
                    version: 4
                    country_code: DE
                    country: Germany
                    region: Hamburg
                    city: Hamburg (Hamburg-Nord)
                    reserved: false
                    location:
                      latitude: 53.5735
                      longitude: 10.0548
                      timezone: Europe/Berlin
                      local_time: '2026-10-15T19:27:05+02:00'
                      utc_offset: '+02:00'
                    country_info:
                      code: DE
                      name: Germany
                      flag: 🇩🇪
                      continent: Europe
                      currency: EUR
                      language: de
                      in_eu: true
                      calling_code: 49
                reserved:
                  summary: Private address
                  value:
                    ip: 192.168.1.20
                    version: 4
                    country_code: ''
                    country: ''
                    region: null
                    city: null
                    reserved: true
                    location:
                      latitude: null
                      longitude: null
                      timezone: null
                      local_time: null
                      utc_offset: null
                    country_info: null
        '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:
    IpGeolocationResult:
      type: object
      required:
        - ip
        - version
        - reserved
        - country_code
        - country
        - region
        - city
        - location
        - country_info
      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.
        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 fields are empty or `null`. Usually
            it means you sent your proxy's address instead of the client's.
        location:
          type: object
          description: >-
            Where `city` is, and the local time there. Every field is `null` for
            `reserved` addresses.
          required:
            - latitude
            - longitude
            - timezone
            - local_time
            - utc_offset
          properties:
            latitude:
              type:
                - number
                - 'null'
              description: >-
                Latitude of `city` in decimal degrees, rounded to 4 decimals. It
                is the city's centre, not the device: treat it as accurate to
                tens of kilometres at best, and to the operator's location for
                mobile networks. `null` when the city is unknown.
            longitude:
              type:
                - number
                - 'null'
              description: >-
                Longitude of `city` in decimal degrees, rounded to 4 decimals.
                Same accuracy as `latitude`. `null` when the city is unknown.
            timezone:
              type:
                - string
                - 'null'
              description: >-
                IANA time zone, such as `America/Los_Angeles`: the zone of the
                nearest city of more than 15,000 people in the same country.
                When the city is unknown, the country's zone if the country has
                only one. `null` otherwise.
            local_time:
              type:
                - string
                - 'null'
              format: date-time
              description: >-
                The current time in `timezone` as RFC 3339 with its offset, such
                as `2026-10-15T10:23:28-07:00`, at the moment of the lookup.
                `null` when `timezone` is `null`.
            utc_offset:
              type:
                - string
                - 'null'
              description: >-
                The current offset of `timezone` from UTC as `±HH:MM`, such as
                `-07:00`. It includes daylight saving time. `null` when
                `timezone` is `null`.
        country_info:
          type:
            - object
            - 'null'
          description: Details of `country_code`. `null` when `country_code` is empty.
          required:
            - code
            - name
            - flag
            - continent
            - currency
            - language
            - in_eu
            - calling_code
          properties:
            code:
              type: string
              description: The ISO 3166-1 alpha-2 code
              the same as `country_code`.: null
            name:
              type: string
              description: The country name in English.
            flag:
              type: string
              description: The emoji flag, such as `🇺🇸`.
            continent:
              type: string
              enum:
                - Africa
                - Antarctica
                - Asia
                - Europe
                - North America
                - Oceania
                - South America
                - ''
              description: >-
                The continent. North America includes Central America and the
                Caribbean. Empty when unknown.
            currency:
              type: string
              description: >-
                ISO 4217 code of the main currency, such as `USD`. Empty when
                unknown.
            language:
              type: string
              description: >-
                ISO 639 code of the main language, such as `en`. Empty when
                unknown.
            in_eu:
              type: boolean
              description: '`true` when the country is a member state of the European Union.'
            calling_code:
              type:
                - integer
                - 'null'
              description: >-
                The international calling code, such as `1` or `44`. `null` when
                unknown.
    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.