GeoApi Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating GeoApi into an application involves a sequence of steps designed to provide access to its geospatial services. Developers begin by creating an account to obtain the necessary credentials. An API key, provided upon registration, acts as the primary authentication method for all requests. Once authenticated, developers can send requests to specific GeoApi endpoints, such as the Geocoding API or Places API, to retrieve location-based data or perform geospatial operations. The platform supports various programming languages for making these calls, with official documentation offering examples in JavaScript, cURL, and Python.

The initial setup process is summarized in the following table:

Create an account and get keys

To access GeoApi's services, an account must first be created on the GeoApi website. This registration process typically requires a valid email address and the creation of a password. Upon successful registration, users gain access to a personal dashboard, which serves as the central hub for managing projects, monitoring usage, and obtaining API keys.

The API key is a unique alphanumeric string that authenticates your requests to GeoApi. It is crucial for both security and billing purposes, allowing GeoApi to track usage against your account's plan. To locate your API key:

1. Navigate to the GeoApi dashboard after logging in.
2. Look for a section labeled 'API Keys' or 'Projects'.
3. Your default API key should be visible. Copy this key, ensuring no extra spaces are included.

It is recommended to store your API key securely and avoid hardcoding it directly into client-side code that could be publicly exposed. For server-side applications, environment variables are a common method for handling API keys. For client-side applications, consider using a proxy server or an authentication mechanism like OAuth if direct client access to the API key is unavoidable, although GeoApi's primary authentication for most services is via the API key appended to the URL as a query parameter.

Your first request

After obtaining an API key, the next step is to make a test request to confirm connectivity and functionality. A common starting point is the Geocoding API, which converts addresses into geographic coordinates (latitude and longitude). This example demonstrates a basic forward geocoding request using cURL, a command-line tool for making HTTP requests:

curl "https://api.geoapify.com/v1/geocode/search?text=380%20Saint%20Paul%20Place%2C%20Baltimore%2C%20MD&apiKey=YOUR_API_KEY"

Replace YOUR_API_KEY with the actual API key retrieved from your GeoApi dashboard. The text parameter specifies the address to be geocoded. The %20 in the address string represents a URL-encoded space character.

A successful response from this request will return a JSON object containing an array of features, each representing a geocoded result. An example of a simplified response structure might look like this:

{
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "380 Saint Paul Place",
        "city": "Baltimore",
        "state": "Maryland",
        "country": "United States",
        "lat": 39.2974,
        "lon": -76.6128,
        "formatted": "380 Saint Paul Place, Baltimore, MD 21202, United States"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-76.6128, 39.2974]
      }
    }
  ],
  "query": {
    "text": "380 Saint Paul Place, Baltimore, MD"
  }
}

The lat and lon properties within the properties object provide the latitude and longitude, respectively. The formatted property offers a human-readable address string. Geocoding is foundational to many location-based services, as detailed in the Google Maps Geocoding API overview.

For developers working with JavaScript, GeoApi provides an SDK. Here is an example using the GeoApi JavaScript SDK to perform a similar geocoding request:

import { GeocodingAPI } from '@geoapify/geocoding-api';

const geoapify = new GeocodingAPI('YOUR_API_KEY');

geoapify.search('380 Saint Paul Place, Baltimore, MD')
  .then(result => {
    console.log(result.features);
  })
  .catch(error => console.error(error));

This JavaScript example assumes the GeoApi SDK has been installed (e.g., via npm). The search method abstracts the HTTP request, returning a Promise that resolves with the geocoding results.

Common next steps

After successfully making a first request, developers often proceed with further integration and exploration of GeoApi's capabilities:

• Explore other APIs: GeoApi offers a suite of services beyond geocoding, including a Places API for point-of-interest search, a Routing API for calculating directions, and a Map Tiles API for custom map rendering. Reviewing the GeoApi documentation can help identify which services best fit specific project requirements.
• Implement error handling: Production-ready applications require robust error handling. GeoApi responses may contain error codes or messages for invalid requests, rate limit exceedances, or other issues. Implement logic to gracefully manage these scenarios.
• Manage API key securely: As applications scale, managing API keys securely becomes critical. Consider using environment variables for server-side applications or exploring token-based authentication if your architecture allows.
• Monitor usage: The GeoApi dashboard provides tools to monitor API usage against your free tier limits or paid plan. Regularly checking these metrics can help avoid unexpected service interruptions or costs.
• Integrate SDKs: For supported languages like JavaScript, leveraging the official GeoApi SDKs can simplify API interactions, providing higher-level abstractions and handling common tasks like request formatting.

Troubleshooting the first call

When the initial API call does not return the expected result, several common issues can be investigated:

• Incorrect API Key: The most frequent issue is an incorrect or expired API key. Double-check that the key copied from the GeoApi dashboard matches the one used in the request. Ensure there are no leading or trailing spaces.
• URL Encoding: Parameters in the URL, especially addresses with spaces or special characters, must be URL-encoded. For instance, spaces should be replaced with %20. Most HTTP client libraries handle this automatically, but with manual cURL requests, it's a common oversight.
• Network Connectivity: Verify that the environment from which the API call is made has active internet access and is not blocked by a firewall or proxy.
• Rate Limits: Even on the free tier, GeoApi imposes request limits (e.g., 3,000 requests per day). If you are rapidly testing, you might hit these limits. Check your GeoApi dashboard for current usage statistics.
• Endpoint Errors: If the API returns an error message, examine the status code and response body. Common HTTP status codes like 400 Bad Request, 401 Unauthorized (often due to an invalid API key), or 403 Forbidden can provide clues. Refer to the GeoApi API reference for specific error codes.
• Syntax Errors: Ensure the request URL is correctly formatted, with parameters and values properly separated by & and =.

Consulting the GeoApi documentation's troubleshooting section can provide more specific guidance for addressing common issues encountered during development.