# Goodreturns — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access real-time and historical gold prices across India. Retrieve daily gold rates for 18k, 22k, and 24k purity levels in INR, compare prices across major Indian cities, and explore recent price trends and monthly summaries.

**Category:** Finance & Markets | **Website:** [goodreturns.in/](https://goodreturns.in/) | **Docs:** [parse.bot/marketplace/d836f6ca-1872-4057-8d74-f95a264e6f4a/goodreturns-in-api](https://parse.bot/marketplace/d836f6ca-1872-4057-8d74-f95a264e6f4a/goodreturns-in-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-goodreturns-in-api-d836f6ca/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_city_historical_summary

Extract monthly historical gold price summaries for a specific Indian city. Returns data for recent months (typically 6-7 months) including opening rate, closing rate, highest/lowest rates with dates, and price trend percentage for 22K and 24K gold.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | No | City name in lowercase. Verified working values: bangalore, mumbai, delhi, chennai, hyderabad, kolkata, pune, ahmedabad. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-goodreturns-in-api-d836f6ca/get_city_historical_summary \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>"}'
```

### get_city_precious_metals_rates

Extract today's gold rates (18K, 22K, 24K) and silver rates for a specific Indian city. Returns gold prices for 1g, 8g, 10g, 100g weights with daily change amounts for each purity level, plus silver prices for 1g, 10g, 100g, 1kg with daily change. Fetches two city-specific pages in one call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `city` | string | Yes | City name in lowercase. Verified working values: mumbai, delhi, bangalore, chennai, hyderabad, kolkata, pune, ahmedabad. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-goodreturns-in-api-d836f6ca/get_city_precious_metals_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"<string>"}'
```

### get_city_wise_rates

Extract current gold price per gram across major Indian cities for 18K, 22K, and 24K purity levels. Returns today's rate for each purity level by city. Typically covers 10+ cities including Chennai, Mumbai, Delhi, Kolkata, Bangalore, Hyderabad, Kerala, Pune, Vadodara, Ahmedabad.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-goodreturns-in-api-d836f6ca/get_city_wise_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_historical_rates

Extract gold rates for 22K and 24K for every day over the last 10 days in India. Each entry contains the date, rate, and daily change for both purity levels. Useful for short-term price trend analysis.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-goodreturns-in-api-d836f6ca/get_historical_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_india_gold_rates

Extract today's gold prices in INR for 18K, 22K, and 24K purity levels in India. Returns rates for 1g, 8g, 10g, and 100g weights with today's price and the daily change amount for each purity. Single-page response keyed by gram weight.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-goodreturns-in-api-d836f6ca/get_india_gold_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_india_precious_metals_rates

Extract today's gold and silver prices in INR for India in a single combined response. Returns gold rates (1g, 8g, 10g, 100g at 18K/22K/24K purity) and silver rates (1g, 10g, 100g, 1kg) with daily changes, plus a UTC timestamp and source attribution. Combines two page fetches into one call for convenience.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-goodreturns-in-api-d836f6ca/get_india_precious_metals_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_india_precious_metals_summary

Extract today's India gold and silver prices in INR as a flat, automation-friendly JSON object with no arrays. Gold rates cover 1g, 8g (sovereign), 10g, and 100g at 18K/22K/24K purity. Silver rates cover 1g, 10g, 100g, and 1kg. All prices and changes are signed integers. Includes a natural-English market_summary describing daily price movement. Combines two page fetches into one call.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-goodreturns-in-api-d836f6ca/get_india_precious_metals_summary \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_india_silver_rates

Extract today's silver prices in INR for India. Returns rates for 1 gram, 10 grams, 100 grams, and 1 kilogram weights with today's price and the daily change amount. Single-page response keyed by weight.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-goodreturns-in-api-d836f6ca/get_india_silver_rates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```