The offline implementation is highly recommended as it eliminates the need to rely on third-party cloud services and it's usually cheaper for medium to big applications. All operations are conducted locally, optimizing both bandwidth usage and response times.

How does it work? It's straightforward: GeoPulse provides a lightweight HTTP server that runs locally on your machine. The server downloads and manages the geolocation database automatically.

Installation

GeoPulse provides pre-built binaries for all major operating systems. Follow these steps to get started:

1. Download the appropriate binary for your operating system:

   Available binaries:

   • GeoPulse-linux-arm - Linux ARM
   • GeoPulse-linux-x86 - Linux x86
   • GeoPulse-macos-arm - macOS ARM (Apple Silicon)
   • GeoPulse-macos-x86 - macOS x86 (Intel)
   • GeoPulse-windows.exe - Windows

   You can find the list of actual binaries at
   https://github.com/GeoPulseData/pulse/tree/main/binaries

   
   

   Using curl (example for Linux ARM):

   curl -L https://github.com/GeoPulseData/pulse/raw/main/binaries/GeoPulse-linux-arm -o geopulse

   Replace GeoPulse-linux-arm with your target binary from the list above.

2. Make the binary executable (Unix-based systems):

   chmod +x ./geopulse

Configuration

You can configure the server using command-line arguments or a configuration file:

Command Line Arguments

./geopulse --port 3456 --key YOUR_API_KEY

• --port - The port number for the server (default: 3456)
• --key - Your GeoPulse API key

Configuration File

Alternatively, you can create a .geopulse file relative to geopulse with your API key. Then you can run the server without the --key argument:

./geopulse --port 3456

GeoPulse will automatically pick the API KEY from the .geopulse file

Usage

Once the server is running, you can use it exactly like the Cloud API. The only difference is the base URL:

http://localhost:3456/ip/{ip}

http://localhost:3456/ip/{ip}?baseCurrency=EUR

Typescript types

In case you want to use this with an environment that uses Typescript, here are the types returned by GeoPule.pro

export interface Country {
    name: string
    code: string
    capital: string
    callingCode: string
    isEUMember: boolean
    currency?: {
        code: string;
        name: string;
        symbol: string;
    };
    flag: {
        svg: string;
        emoji: string
    }
    continent: {
        name: string;
        code: string;
    }
    language: {
        name: string;
        code: string
    }
}

export interface IPGeoPulse {
    ip: string,

    latitude?: string,
    longitude?: string,
    isMobile?: string,
    city?: string,
    state?: string,
    zip?: string,

    country: Country,
    exchangeRateBaseCurrency?: string,
    exchangeRate?: number,
    timeZone?: {
        name: string,
        localTime: string,
        localTimeUnix: string,
    },
}

Network Configuration

http://localhost:3456

http://your-geopulse-server:3456