IP API

Privacy-focused IP geolocation API.

Live · Report a Bug · Request a Feature

---

Features

• Sub-100ms responses via Vercel's edge network
• No logging, no tracking, no data storage
• Accurate geolocation data for IPs worldwide
• No API keys required
• Open source and free to use
• Minimal response payload

Quick Start

curl https://ip.hmddevs.org

{
  "ip": "8.8.8.8",
  "country": "US"
}

API

Endpoint

GET https://ip.hmddevs.org/

Response Fields

Field	Type	Description
ip	string	The client's public IP address
country	string	ISO 3166-1 alpha-2 country code (e.g. US, DE, JP)

Status Codes

Code	Description
200	Successful response

Usage Examples

JavaScript (Fetch)

fetch('https://ip.hmddevs.org')
  .then(response => response.json())
  .then(data => {
    console.log(`IP: ${data.ip}`);
    console.log(`Country: ${data.country}`);
  });

JavaScript (Async/Await)

const getLocation = async () => {
  const response = await fetch('https://ip.hmddevs.org');
  const { ip, country } = await response.json();
  return { ip, country };
};

Python

import requests

response = requests.get('https://ip.hmddevs.org')
data = response.json()
print(f"IP: {data['ip']}, Country: {data['country']}")

cURL

curl -s https://ip.hmddevs.org | jq

PHP

<?php
$response = file_get_contents('https://ip.hmddevs.org');
$data = json_decode($response, true);
echo "IP: " . $data['ip'] . ", Country: " . $data['country'];
?>

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type IPResponse struct {
    IP      string `json:"ip"`
    Country string `json:"country"`
}

func main() {
    resp, _ := http.Get("https://ip.hmddevs.org")
    defer resp.Body.Close()

    var data IPResponse
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Printf("IP: %s, Country: %s\n", data.IP, data.Country)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://ip.hmddevs.org')
response = Net::HTTP.get(uri)
data = JSON.parse(response)
puts "IP: #{data['ip']}, Country: #{data['country']}"

Rust

use reqwest;
use serde::Deserialize;

#[derive(Deserialize)]
struct IpResponse {
    ip: String,
    country: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let resp: IpResponse = reqwest::get("https://ip.hmddevs.org")
        .await?
        .json()
        .await?;
    println!("IP: {}, Country: {}", resp.ip, resp.country);
    Ok(())
}

Self-Hosting

Prerequisites

• Node.js 18+
• Vercel CLI (optional)

Installation

git clone https://github.com/hmddevs/ip-api.git
cd ip-api
npm install

Local Development

npm run dev

Visit http://localhost:3000 to test locally.

Deploy to Vercel

Or via CLI:

npm install -g vercel
vercel --prod

Project Structure

ip-api/
├── api/
│   └── index.js            # Main API handler
├── test/
│   └── api.test.js         # Unit tests
├── .github/
│   ├── ISSUE_TEMPLATE/     # Issue templates
│   ├── workflows/          # CI/CD
│   └── dependabot.yml      # Dependency updates
├── openapi.yaml            # OpenAPI 3.1 specification
├── package.json
├── vercel.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── LICENSE

Scripts

npm run dev          # Start development server
npm run lint         # Run linting
npm run lint:fix     # Fix linting issues
npm test             # Run tests
npm run deploy       # Deploy to production

Contributing

See CONTRIBUTING.md for guidelines.

Security

Found a vulnerability? See SECURITY.md.

Licence

MIT

Acknowledgements

• MaxMind GeoLite2 for geolocation data
• geoip-lite for the Node.js geolocation library
• Vercel for hosting

---

Copyright 2025 HMD Developments, Inc.