ipgeo_sdk/README.md

A TypeScript SDK for interacting with the IPGeo API, providing fast and reliable geolocation services.

# ipgeo_sdk

A simple JavaScript/TypeScript SDK for accessing the ipgeo FastAPI service.

Visit [ipgeo.dev](https://ipgeo.dev) for more details and to get your API key today.

## Features

- Fetch geo data for any IP address
- Easy API key authentication
- TypeScript types included
- Works in Node.js and browser environments

## Quick Start

### TypeScript/Node.js (Recommended: utils.ts)

Create a `utils.ts` file to initialize and export your SDK client for reuse:

```ts
// utils.ts
import { IPGeoSdk } from "ipgeo_sdk";

export const ipGeoClient = new IPGeoSdk({
  apiKey: process.env.IPGEO_API_KEY,
});
```

Then use it in your app:

```ts
import { ipGeoClient } from "./utils";

ipGeoClient.getGeoData("8.8.8.8").then((data) => {
  console.log(data);
});
```

### Vanilla JavaScript

```js
const { IPGeoSdk } = require("ipgeo_sdk");

const ipGeoClient = new IPGeoSdk({
  apiKey: "YOUR_API_KEY",
});

ipGeoClient.getGeoData("8.8.8.8").then((data) => {
  console.log(data);
});
```

### Next.js

```ts
// In your Next.js API route or getServerSideProps:
import { ipGeoClient } from "../utils";

export default async function handler(req, res) {
  const data = await ipGeoClient.getGeoData("8.8.8.8");
  res.status(200).json(data);
}
```

### Angular

```ts
// In your Angular service:
import { Injectable } from "@angular/core";
import { ipGeoClient } from "../utils";

@Injectable({ providedIn: "root" })
export class IpGeoService {
  async getGeo(ip: string) {
    return ipGeoClient.getGeoData(ip);
  }
}
```

## API

- `getGeoData(ip: string)`: Fetch geo data for an IP address. Returns an object with location, timezone, and currency info.

## TypeScript Types

```ts
export interface IpGeoResponse {
  ip_range_start: string;
  ip_range_end: string;
  continent_code: string;
  country_code: string;
  state: string;
  city: string;
  latitude: number;
  longitude: number;
  timezone: string;
  currency: {
    abbreviation: string;
    currency_name: string;
  };
}
```

## Security Note

**Do not expose your API key in client-side code or public repositories.**  
For best security, use the SDK in server-side components (such as Next.js API routes, getServerSideProps, or backend services).  
Never embed your API key directly in frontend code or static files.

## Usage Notes

- Requires an API key from your ipgeo account.
- For local development, see the main README for environment variable setup and testing instructions.

---

For more details, usage examples, and contributing guidelines, see the full documentation in the main repository.