Quickstart

Make your first IP geolocation request in under 5 minutes.

1. Create an Account

Sign up for a free NetLoc8 account at dashboard.netloc8.com. No credit card required. Your free plan includes 5,000 requests/month.

After signing up, go to the API Keys section in your dashboard and create your first key. You'll get two types:

  • Secret keys (sk_live_...) — for server-side use
  • Publishable keys (pk_live_...) — for client-side / browser use

2. Make Your First Request

The fastest way to test is with curl. This looks up the caller's own IP address:

Bash
curl -H "X-API-Key: sk_live_YOUR_KEY" \
  https://api.netloc8.com/v1/ip/me

Or look up a specific IP:

Bash
curl -H "X-API-Key: sk_live_YOUR_KEY" \
  https://api.netloc8.com/v1/ip/8.8.8.8

You'll get a response like:

JSON
{
    "query": { "type": "ip", "value": "8.8.8.8", "ipVersion": 4 },
    "location": {
        "continent": { "code": "NA", "name": "North America" },
        "country": { "code": "US", "name": "United States", "flag": "🇺🇸" },
        "region": { "code": "CA", "name": "California" },
        "city": "Mountain View",
        "timezone": "America/Los_Angeles",
        "coordinates": { "latitude": 37.386, "longitude": -122.084 }
    },
    "network": { "asn": "AS15169", "organization": "Google LLC" },
    "meta": { "precision": "city" }
}

3. Install the SDK

Choose the SDK that matches your stack:

Next.js
bun add @netloc8/nextjs
React
bun add @netloc8/react
Node.js / Universal
bun add @netloc8/core

Package managers

All packages also work with npm install, yarn add, and pnpm add.

4. Use in Your Code

Next.js (Server Component)

app/page.jsx
import { getGeo } from '@netloc8/nextjs/server';

export default async function Page() {
    const geo = await getGeo();

    return (
        <div>
            <p>Hello from {geo.location?.city}, {geo.location?.country?.name}</p>
            <p>Timezone: {geo.location?.timezone}</p>
        </div>
    );
}

React (Client-Side)

App.jsx
import { NetLoc8Provider, useGeo } from '@netloc8/react';

function App() {
    return (
        <NetLoc8Provider apiKey="pk_live_YOUR_KEY">
            <LocationBanner />
        </NetLoc8Provider>
    );
}

function LocationBanner() {
    const { geo, isLoading } = useGeo();
    if (isLoading) return <p>Detecting location…</p>;
    return <p>Hello from {geo.location?.city}</p>;
}

Node.js / Server-Side

server.js
import { fetchGeo } from '@netloc8/core';

const geo = await fetchGeo('203.0.113.42', {
    apiKey: process.env.NETLOC8_API_KEY,
});

console.log(geo.location?.country?.code); // "US"
console.log(geo.location?.city);          // "Mountain View"
console.log(geo.location?.timezone);      // "America/Los_Angeles"

Next Steps