Forward and Reverse Address Geocoding with Geocodeapi

For a delivery form, an address may need to become a point on a map. Geocodeapi’s legacy examples use forward geocoding to turn address text into coordinates and reverse geocoding to turn coordinates into an address or place description.

I’ll show how to construct both requests and check a returned match before using it.

TL;DR

Forward geocoding turns address text into coordinates, while reverse geocoding uses coordinates to find address context. Geocodeapi’s legacy examples use separate search and reverse endpoints, but confirm their current parameters in the provider’s account documentation before relying on them.

• Forward: `/api/v1/search` with a text query and API key.
• Reverse: `/api/v1/reverse` with latitude, longitude and API key.
• Inspect the response and validate the selected match before saving or acting on it.

What forward and reverse geocoding return

Forward geocoding searches for a place from text, then returns location data such as coordinates. Reverse geocoding starts with a coordinate pair and returns a human-readable address or nearby place context.

The two operations answer different questions. A delivery form may start with an address and need a map point, while a phone app may have a GPS point and need a label. Google’s geocoding overview describes both directions and notes that results can include address components and types.

The returned address is a description associated with a point. It is not independent proof of a property boundary or entrance. I use the distinction here to keep a returned place label separate from address verification.

Geocodeapi’s documentation index and the existing CodeForGeek example show a legacy API shape: `/api/v1/search` for forward lookup and `/api/v1/reverse` for reverse lookup. The public reference was not readable beyond its index during this research, so check the account docs before relying on these routes.

How to call Geocodeapi for both directions

Make one request for the direction you need, then inspect its result before using the location. The examples below follow the legacy endpoint shape documented in the existing article and the Geocodeapi documentation search excerpt.

Step 1: Prepare an API key and encode the address

Create or retrieve an API key through Geocodeapi’s official account flow, then keep it on a server you control. Do not commit a working credential to source control or embed it in a public web page: both can expose the key to people who should not use it.

Address text may contain spaces, commas or non-ASCII characters. Let your HTTP client encode query parameters rather than concatenating raw user input into a URL. Keep the address as one text parameter, and include enough context, such as a city or country, to reduce matches to similarly named places.

Step 2: Send a forward lookup

The search route accepts a place description in the legacy example. The original article uses the `text` query parameter and `apikey` credential name. Do not substitute names from another provider without checking Geocodeapi’s documentation.

curl --get 'https://app.geocodeapi.io/api/v1/search' \
  --data-urlencode 'text=Mumbai, India' \
  --data-urlencode 'apikey=YOUR_API_KEY'

The command asks curl to encode each query parameter. Replace the placeholder locally with your key, not in a committed file or screenshot. No live request was run for this draft because no Geocodeapi key or accessible current API reference was available.

Step 3: Send a reverse lookup

Reverse lookup sends a latitude and longitude instead of address text. The legacy example expresses them as separate dotted parameter names, `point.lat` and `point.lon`. Confirm that spelling in the current account documentation before deploying.

curl --get 'https://app.geocodeapi.io/api/v1/reverse' \
  --data-urlencode 'point.lat=48.858268' \
  --data-urlencode 'point.lon=2.294471' \
  --data-urlencode 'apikey=YOUR_API_KEY'

Latitude describes north-to-south position and longitude describes east-to-west position. The sample uses a point near the Eiffel Tower, but the response should be checked rather than assumed. Do not reverse the two values: both can be valid numbers while locating a different place.

Step 4: Check the request construction

The script below only constructs query URLs. It does not contact Geocodeapi or prove that its legacy routes remain active. The printed output shows URL encoding for the forward address and preserves each reverse coordinate as a separate parameter:

Forward request: https://app.geocodeapi.io/api/v1/search?text=Mumbai%2C+India&apikey=YOUR_API_KEY
Reverse request: https://app.geocodeapi.io/api/v1/reverse?point.lat=48.858268&point.lon=2.294471&apikey=YOUR_API_KEY

In the forward URL, the comma is encoded as `%2C` so it remains part of the address value. The reverse URL keeps `point.lat` and `point.lon` distinct. This local check validates URL construction only, not the provider’s response.

Before using returned data in an application, parse the response according to the provider’s current schema. Verify required fields exist and handle an empty result set separately from a network error. If the service returns several candidates, display enough context for a person or your own matching rule to choose one.

Do not assume a first candidate is always correct. A provider may rank plausible results, but the application still knows whether the submitted country, postal code or unit number matters. Compare those fields with the original input, and leave the result unconfirmed when a required component is absent.

Step 5: Check the response before using a match

Check the HTTP status before parsing the body, then confirm that the response contains a usable result and the expected address components. A successful HTTP response means the request reached the service. It does not prove that a candidate is the address you intended.

For a forward query, compare the returned place, region and country with the input. For a reverse query, consider whether the returned item is a building, street, neighborhood or broader area. The field names and response structure are provider-specific, so use Geocodeapi’s current schema rather than copying a response parser from Google, Mapbox or Geoapify.

Keep the original query and the chosen result together when your application needs an audit trail. If the result is used for delivery, billing or eligibility, add a user confirmation step or a separate authoritative validation source. A geocoding match alone does not verify that someone lives at that address.

Common errors with ambiguous addresses and failed lookups

When the returned location does not match the intended place, check the input and the candidate before retrying. A short place name can refer to locations in several countries, and an incomplete street address can resolve only to a street or city.

Do not assume a particular error code or JSON field without the provider’s current response reference. Capture the status and a redacted response body for debugging, but remove API keys and personal address data before sharing logs.

Reverse geocoding is also approximate in a practical sense: a coordinate can sit near multiple address features or fall in a place without a conventional street address. A map pin can be on a road, courtyard or parcel boundary while the returned label names a nearby mapped feature. Choose how much detail your application needs, and label a neighborhood-level result as an area rather than a precise street address.

For deeper address-field parsing, see Extract Address Information Using Geocodeapi. For another provider’s paired forward and reverse workflow, see the Positionstack geocoding guide.

Conclusion

Choose the endpoint that matches the data your application already has. Before using a returned candidate, compare its available address details with the original input and your required level of precision.

For the general distinction, read Google’s geocoding overview. For provider-specific integration, start with the Geocodeapi documentation index and the documentation available in your account. Keep the provider’s API contract close to your integration tests, since endpoint paths and response fields can change independently of the general geocoding concepts.

FAQ

These answers distinguish the two request directions and the limits of interpreting a match.