Geoapify Getting Started: Account, Keys, and First API Call

Getting started overview

Getting started with Geoapify involves a sequence of steps designed to enable quick API integration. This guide outlines the process from account creation and API key generation to making an initial API request. Geoapify provides various APIs for mapping and geospatial services, including geocoding, place search, and routing functionality Geoapify API documentation. Developers typically authenticate requests using an API key.

The core process includes:

1. Account Creation: Registering on the Geoapify platform.
2. API Key Generation: Obtaining a unique key from the developer dashboard.
3. First Request: Constructing and executing an API call, often using the Geocoding API.

Geoapify offers a free tier that allows up to 3,000 requests per day, which is suitable for initial development and testing Geoapify pricing details. For higher volumes or specific features like batch geocoding, paid plans are available.

Here is a quick reference table for the getting started process:

Create an account and get keys

To begin using Geoapify services, account creation and API key retrieval are necessary. This process establishes your identity with the platform and provides the credentials required for authentication.

1. Sign up for a Geoapify account

Navigate to the Geoapify sign-up page. You can register using an email address and password, or through third-party authentication providers such as Google or GitHub. Completing the registration process grants access to the Geoapify client dashboard.

2. Access your API key

Upon successful registration and login, you are directed to the Geoapify client dashboard. Your API key is typically displayed on the main dashboard page or within the "Projects" section Geoapify Projects dashboard. Geoapify automatically generates a default API key for new accounts. This key acts as a unique identifier for your requests and is used to track usage against your free tier limits or subscribed plans.

It is recommended to store your API key securely and not embed it directly in client-side code that could be publicly exposed.

Your first request

After obtaining an API key, you can make your first API call. The Geocoding API is often used for initial testing due to its straightforward request structure. This API converts an address into geographic coordinates (latitude and longitude).

Example: Geocoding API request

Let's use the Geocoding API to find the coordinates for "Eiffel Tower, Paris".

API endpoint

The Geocoding API endpoint for forward geocoding (address to coordinates) is:

https://api.geoapify.com/v1/geocode/search

Required parameters

• text: The address or place name to geocode.
• apiKey: Your Geoapify API key.

Constructing the request

You can construct this request using various tools or programming languages. Here are examples using cURL and JavaScript.

cURL example

Replace YOUR_API_KEY with your actual Geoapify API key.

curl "https://api.geoapify.com/v1/geocode/search?text=Eiffel%20Tower%2C%20Paris&apiKey=YOUR_API_KEY"

JavaScript example (fetch API)

This example demonstrates how to make the request in a web browser or Node.js environment using the fetch API.

const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
const address = 'Eiffel Tower, Paris';
const encodedAddress = encodeURIComponent(address);

fetch(`https://api.geoapify.com/v1/geocode/search?text=${encodedAddress}&apiKey=${apiKey}`)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log(data);
    // Process the geocoding results
    if (data.features && data.features.length > 0) {
      const firstResult = data.features[0];
      console.log('Latitude:', firstResult.geometry.coordinates[1]);
      console.log('Longitude:', firstResult.geometry.coordinates[0]);
    }
  })
  .catch(error => {
    console.error('Error fetching geocoding data:', error);
  });

Expected response structure

A successful response returns a JSON object containing a features array, with each feature representing a geocoded result. The coordinates are typically found within the geometry.coordinates array of a feature Geoapify Geocoding API documentation.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Eiffel Tower",
        "country": "France",
        "city": "Paris",
        "lat": 48.85826, // Example latitude
        "lon": 2.29449,  // Example longitude
        // ... other properties
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          2.29449, // Longitude
          48.85826 // Latitude
        ]
      }
    }
  ]
}

The geometry.coordinates array follows the GeoJSON standard, which specifies [longitude, latitude] order GeoJSON RFC 7946 coordinates standard.

Common next steps

After successfully making your first API call, you can explore additional Geoapify features and integrate them into your applications. Common next steps include:

• Exploring other APIs: Investigate the Places API for points of interest, the Routing API for directions, or the Map Tiles API for custom maps Geoapify API overview.
• Implementing advanced geocoding: Utilize features like reverse geocoding (coordinates to address), batch geocoding, or geocoding with biasing parameters.
• Integrating SDKs: For web applications, consider using the Geoapify JavaScript SDK for map display and interactive elements, simplifying client-side development Geoapify JavaScript Map Library documentation.
• Monitoring usage: Regularly check your API usage in the Geoapify client dashboard to stay within your free tier limits or monitor your paid plan consumption.
• Securing your API key: For production applications, implement server-side proxies or environment variables to protect your API key and prevent unauthorized usage.
• Handling errors and rate limits: Implement robust error handling in your code to manage unsuccessful API calls and respect rate limits to avoid temporary blocks.

Troubleshooting the first call

If your first API request to Geoapify does not return the expected results, consider the following troubleshooting steps:

• Check API Key: Ensure your API key is correctly copied and pasted into the request. Verify there are no extra spaces or missing characters.
• Verify Endpoint URL: Confirm that the API endpoint URL is accurate and matches the documentation for the specific API you are using. Typographical errors in the URL are common issues.
• Inspect Parameters: Double-check that all required parameters are included and correctly formatted. For the Geocoding API, ensure the text parameter is present and properly URL-encoded.
• Review Network Connectivity: Ensure your development environment has an active internet connection and is not blocked by a firewall or proxy.
• Examine the Response: If you receive an error response, carefully read the error message. Geoapify typically provides descriptive error codes and messages that can indicate the problem, such as "Invalid API Key" or "Missing required parameter" Geoapify General API documentation on errors.
• URL Encoding: When passing addresses or special characters in URL parameters, ensure they are properly URL-encoded (e.g., spaces become %20). Most HTTP client libraries handle this automatically, but manual construction requires attention.
• CORS Issues (Browser-side): If making requests directly from a web browser, Cross-Origin Resource Sharing (CORS) policies might block the request. Geoapify's APIs are generally configured to handle CORS for typical website origins, but misconfigurations on the client-side or specific browser extensions can interfere.
• Check Daily Quota: Verify your API usage in the Geoapify dashboard to ensure you haven't exceeded your daily request limit, especially if you are on the free tier.