Geocoding API

Convert physical addresses into geographic coordinates (latitude and longitude).

The Geocoding API converts human-readable addresses into geographic coordinates (latitude and longitude). This is essential for mapping applications, location-based services, and spatial analysis.

Endpoint

GET /api/v1/geocode

Authentication

Requires API key authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Parameters

Address Format Guidelines

The address parameter accepts various formats:

• Full address: "1600 Amphitheatre Parkway, Mountain View, CA 94043"
• Street address: "1600 Amphitheatre Parkway"
• City and state: "Mountain View, CA"
• Postal code: "94043"
• Landmark: "Golden Gate Bridge"

Response Format

Success Response

{
  "latitude": 37.4224764,
  "longitude": -122.0842499,
  "formatted_address": "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA"
}

Response Fields

Error Responses

Address Not Found

{
  "error": {
    "code": 404,
    "message": "Address not found"
  }
}

Status Code: 404 Not Found

Missing Required Parameter

{
  "error": {
    "code": 400,
    "message": "Address parameter is required"
  }
}

Status Code: 400 Bad Request

Invalid API Key

{
  "error": {
    "code": 401,
    "message": "Invalid API key"
  }
}

Status Code: 401 Unauthorized

Rate Limit Exceeded

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded"
  }
}

Status Code: 429 Too Many Requests

Insufficient Balance

{
  "error": {
    "code": 402,
    "message": "Insufficient balance. Please add funds to continue."
  }
}

Status Code: 402 Payment Required

Service Error

{
  "error": {
    "code": 500,
    "message": "Internal Server Error"
  }
}

Status Code: 500 Internal Server Error

Code Examples

cURL

curl -X GET "https://core.streetverify.com/api/v1/geocode?address=1600%20Amphitheatre%20Parkway%2C%20Mountain%20View%2C%20CA" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (Fetch API)

const geocodeAddress = async (address) => {
  const params = new URLSearchParams({
    address: address
  });

  const response = await fetch(`https://core.streetverify.com/api/v1/geocode?${params}`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || `HTTP error! status: ${response.status}`);
  }

  return await response.json();
};

// Usage
try {
  const result = await geocodeAddress('1600 Amphitheatre Parkway, Mountain View, CA');
  console.log(`Coordinates: ${result.latitude}, ${result.longitude}`);
  console.log(`Address: ${result.formatted_address}`);
} catch (error) {
  console.error('Geocoding failed:', error);
}

Python

import requests
from urllib.parse import urlencode

def geocode_address(address, api_key):
    base_url = "https://core.streetverify.com/api/v1/geocode"
    headers = {
        "Authorization": f"Bearer {api_key}"
    }
    params = {
        "address": address
    }
    
    response = requests.get(base_url, params=params, headers=headers)
    response.raise_for_status()
    
    return response.json()

# Usage
try:
    result = geocode_address(
        "1600 Amphitheatre Parkway, Mountain View, CA",
        "YOUR_API_KEY"
    )
    print(f"Coordinates: {result['latitude']}, {result['longitude']}")
    print(f"Address: {result['formatted_address']}")
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Node.js (Axios)

const axios = require('axios');

class GeocodeClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://core.streetverify.com';
  }

  async geocode(address, country = null) {
    try {
      const params = { address };
      if (country) params.country = country;

      const response = await axios.get('/api/v1/geocode', {
        baseURL: this.baseURL,
        params,
        headers: {
          'Authorization': `Bearer ${this.apiKey}`
        }
      });

      return response.data;
    } catch (error) {
      if (error.response) {
        throw new Error(`API Error: ${error.response.data.error?.message || 'Unknown error'}`);
      }
      throw error;
    }
  }
}

// Usage
const client = new GeocodeClient('YOUR_API_KEY');
client.geocode('1600 Amphitheatre Parkway, Mountain View, CA')
  .then(result => {
    console.log(`Formatted: ${result.formatted_address}`);
    console.log(`Coordinates: ${result.latitude}, ${result.longitude}`);
  })
  .catch(error => {
    console.error('Geocoding failed:', error.message);
  });

Use Cases

1. Store Locator

Find the nearest store locations to a customer’s address:

// Geocode customer address
const customerLocation = await geocodeAddress(customerAddress);

// Calculate distances to stores
const nearestStores = stores
  .map(store => ({
    ...store,
    distance: calculateDistance(
      customerLocation.latitude,
      customerLocation.longitude,
      store.latitude,
      store.longitude
    )
  }))
  .sort((a, b) => a.distance - b.distance)
  .slice(0, 5);

2. Delivery Zone Validation

Check if an address falls within your delivery area:

const isInDeliveryZone = (lat, lng, zones) => {
  return zones.some(zone => {
    const distance = calculateDistance(lat, lng, zone.centerLat, zone.centerLng);
    return distance <= zone.radiusKm;
  });
};

const location = await geocodeAddress(deliveryAddress);
const canDeliver = isInDeliveryZone(
  location.latitude,
  location.longitude,
  deliveryZones
);

3. Address Standardization

Ensure consistent address formatting in your database:

const standardizeAddress = async (rawAddress) => {
  const result = await geocodeAddress(rawAddress);
  return result.formatted_address;
};

// Before: "1600 amphitheatre pkwy mountain view"
// After: "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA"

Best Practices

1. Input Validation

Always validate and sanitize address input:

const sanitizeAddress = (address) => {
  return address
    .trim()
    .replace(/\s+/g, ' ')  // Replace multiple spaces with single space
    .substring(0, 500);     // Limit length
};

2. Error Handling

Implement robust error handling for different scenarios:

const geocodeWithFallback = async (address) => {
  try {
    return await geocodeAddress(address);
  } catch (error) {
    if (error.status === 404) {
      // Try with less specific address
      const simplified = address.split(',')[0];
      return await geocodeAddress(simplified);
    }
    throw error;
  }
};

3. Caching

Cache geocoding results to reduce API calls:

const geocodeCache = new Map();

const geocodeWithCache = async (address) => {
  const cacheKey = address.toLowerCase().trim();
  
  if (geocodeCache.has(cacheKey)) {
    return geocodeCache.get(cacheKey);
  }
  
  const result = await geocodeAddress(address);
  geocodeCache.set(cacheKey, result);
  
  return result;
};

4. Batch Processing

For multiple addresses, implement rate-limited batch processing:

const geocodeBatch = async (addresses, delayMs = 100) => {
  const results = [];
  
  for (const address of addresses) {
    try {
      const result = await geocodeAddress(address);
      results.push({ address, result });
    } catch (error) {
      results.push({ address, error: error.message });
    }
    
    // Rate limiting
    await new Promise(resolve => setTimeout(resolve, delayMs));
  }
  
  return results;
};

Rate Limits

The Geocoding API is subject to the following rate limits:

All accounts operate on a pay-as-you-go model at $0.01 per request. Minimum credit purchase is $50 via crypto (USDT on Ethereum).

Monitor your usage via the response headers:

• X-RateLimit-Limit: Maximum requests per minute
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Unix timestamp when limit resets

Related Endpoints

• Reverse Geocoding - Convert coordinates to addresses
• Address Verification - Validate address deliverability
• Autocomplete - Real-time address suggestions