Getting started overview

This guide provides the necessary steps to begin using the Battuta API for geocoding, reverse geocoding, and IP geolocation. It covers account creation, API key retrieval, and making your initial API call. Battuta is designed for developers seeking straightforward location services without extensive advanced features, offering a free tier for low-volume usage.

To successfully make your first request, follow these steps:

Step What to Do Where
1. Create Account Register for a new Battuta account. Battuta homepage
2. Get API Key Locate your unique API key in your dashboard. Battuta dashboard
3. Make Request Construct and execute an API call using your key. Your preferred development environment (e.g., cURL, JavaScript)
4. Parse Response Process the JSON output from the API. Your application logic

Create an account and get keys

To access the Battuta API, you must first create an account and obtain an API key. This key authenticates your requests and links them to your usage plan, which includes a free tier of 2,500 requests per month, as detailed on the Battuta pricing page.

  1. Navigate to the Battuta Homepage: Open your web browser and go to battuta.io.
  2. Sign Up: Look for a "Sign Up" or "Get Started" button and follow the prompts to create a new account. This typically involves providing an email address and creating a password.
  3. Verify Email (if applicable): Some services require email verification before full account access. Check your inbox for a verification link if prompted.
  4. Access Dashboard: Once logged in, you will be directed to your Battuta user dashboard.
  5. Locate API Key: On your dashboard, find the section labeled "API Keys" or similar. Your unique API key will be displayed here. It's usually a long alphanumeric string. Copy this key, as it is required for all API requests.

Keep your API key secure and do not expose it in client-side code without appropriate proxying or environmental variables. For more information on securing API keys, consult general best practices for Google Maps API key security, which apply broadly to various API services.

Your first request

With your API key in hand, you can now make your first request. This example uses the Geocoding API, which converts a human-readable address into geographic coordinates (latitude and longitude). Battuta also offers a Reverse Geocoding API to convert coordinates back to an address and an IP Geolocation API to determine location from an IP address, as described in the Battuta documentation.

Geocoding an address (cURL example)

This cURL command demonstrates how to geocode the address "1600 Amphitheatre Parkway, Mountain View, CA". Replace YOUR_API_KEY with the actual API key you obtained from your dashboard.

curl -X GET "https://api.battuta.io/geocode/v1/json?address=1600%20Amphitheatre%20Parkway,%20Mountain%20View,%20CA&key=YOUR_API_KEY"

Expected Response (JSON):

{
  "status": "success",
  "data": [
    {
      "latitude": 37.4224764,
      "longitude": -122.0842499,
      "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "components": {
        "house_number": "1600",
        "street": "Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "CA",
        "postcode": "94043",
        "country": "USA"
      }
    }
  ]
}

Geocoding an address (JavaScript example)

Battuta offers an official JavaScript SDK. This example uses a simple fetch request, which is often sufficient for basic integrations. For more complex applications, consider using the Battuta JavaScript SDK for potentially enhanced functionality and easier integration.

async function geocodeAddress(address, apiKey) {
  const encodedAddress = encodeURIComponent(address);
  const url = `https://api.battuta.io/geocode/v1/json?address=${encodedAddress}&key=${apiKey}`;

  try {
    const response = await fetch(url);
    const data = await response.json();
    if (data.status === 'success') {
      console.log('Geocoding Result:', data.data[0]);
    } else {
      console.error('Geocoding Error:', data.message);
    }
  } catch (error) {
    console.error('Network or parsing error:', error);
  }
}

const myAddress = "Eiffel Tower, Paris";
const myApiKey = "YOUR_API_KEY"; // Replace with your actual API key
geocodeAddress(myAddress, myApiKey);

Reverse Geocoding (cURL example)

To convert coordinates back to an address, use the Reverse Geocoding API. This example uses the coordinates for the Eiffel Tower.

curl -X GET "https://api.battuta.io/reverse-geocode/v1/json?lat=48.8584&lon=2.2945&key=YOUR_API_KEY"

IP Geolocation (cURL example)

To determine location based on an IP address, use the IP Geolocation API. You can specify an IP address or leave it blank to use the request's source IP.

curl -X GET "https://api.battuta.io/ip-geocode/v1/json?ip=8.8.8.8&key=YOUR_API_KEY"

Common next steps

After successfully making your first API call, consider these common next steps to integrate Battuta further into your application:

  • Error Handling: Implement robust error handling in your code to manage various API responses, including rate limit errors, invalid API keys, or no results found. The Battuta error documentation provides details on common error codes.
  • Rate Limiting: Be aware of your plan's rate limits. The free tier allows 2,500 requests per month. For higher volumes, consider upgrading your plan through the Battuta pricing page.
  • Asynchronous Requests: For web applications, ensure API calls are made asynchronously to prevent blocking the main thread and ensure a responsive user experience.
  • Caching: Implement caching for frequently requested addresses or coordinates to reduce API calls and improve performance.
  • Explore Other Endpoints: Review the comprehensive Battuta API reference to understand the full capabilities, including reverse geocoding and IP geolocation.
  • Environment Variables: Store your API key as an environment variable rather than hardcoding it directly into your application code, especially in production environments. This is a standard security practice for applications interacting with external APIs, as advised by general API security guidelines like those for AWS access keys best practices.

Troubleshooting the first call

If your first API call does not work as expected, review the following common issues and troubleshooting steps:

  • Invalid API Key: Double-check that you have copied your API key correctly from your Battuta dashboard. Ensure there are no extra spaces or missing characters.
  • Missing API Key: Verify that the key parameter is included in your request URL. All Battuta API requests require a valid key.
  • Incorrect Endpoint: Ensure you are using the correct endpoint for the specific API you are trying to access (e.g., /geocode/v1/json, /reverse-geocode/v1/json, /ip-geocode/v1/json). Refer to the Battuta documentation for endpoint specifics.
  • URL Encoding: When sending addresses with spaces or special characters, ensure the address parameter is properly URL-encoded. The JavaScript example above demonstrates encodeURIComponent().
  • Rate Limit Exceeded: If you receive a 429 Too Many Requests error, you may have exceeded your plan's request limit. Check your dashboard for current usage or wait for the next billing cycle.
  • Network Issues: Verify your internet connection. If using cURL, try a simple request to a known working URL (e.g., curl https://example.com) to confirm network connectivity.
  • Firewall/Proxy: If you are making requests from a restricted network, a firewall or proxy might be blocking outbound API calls. Consult your network administrator.
  • Response Status: Always check the status field in the JSON response. If it's not "success", the message field will often provide more details about the error.