How to Use Positionstack for Forward and Reverse Geocoding

Location lookups can start with a place name or a coordinate pair. Positionstack is a geocoding service: it converts address text into coordinates and uses coordinates to return location details.

This article shows how to build both requests and check the returned candidates before your application uses one.

TL;DR: Positionstack geocodes addresses in both directions

Positionstack’s forward endpoint turns an address or place query into geographic coordinates, while its reverse endpoint accepts coordinates and returns location details. Both requests use an API key and return structured data that your application should inspect before using.

• Forward geocoding takes text as input.
• Reverse geocoding takes latitude and longitude as input.
• Use HTTPS, keep the key out of public source code, and validate the returned match.

What is forward and reverse geocoding?

Forward geocoding takes address text to coordinates. Reverse geocoding uses coordinates to find address details.

Positionstack exposes these jobs through separate REST endpoints. A REST API accepts an HTTP request and returns data, commonly JSON, so an application can use the result without scraping a web page. The provider’s current site describes JSON, XML, and GeoJSON response formats.

The direction matters because the input has a different shape. An address is text, while coordinates are a numeric point.

The Positionstack FAQ says a successful lookup can return multiple potential results with confidence scores.

Mapbox explains how its own service ranks candidate features, a useful reminder that providers can use different result models.

How to use Positionstack for forward and reverse geocoding

Build the request from the task, URL-encode its query value, and send it to the matching HTTPS endpoint with your account’s access key. I used URL encoding in the local example because address text contains spaces and punctuation.

Step 1: Prepare an API key and a query

Positionstack’s official documentation describes API-key authentication and HTTPS. Create or retrieve a key through the provider’s account flow, then keep it in a server-side environment variable or secret manager rather than committing it to a repository.

For a forward lookup, choose a complete address or place name. For a reverse lookup, use decimal latitude and longitude.

A browser client sends its API request where users can inspect it, so use a server-side proxy if the key must remain private. Otherwise, confirm that the provider supports a restricted public key for browser use.

Step 2: Build a forward-geocoding request

Send the address text to the forward endpoint as its query. URL encoding converts spaces and punctuation into safe query-string characters, so the address remains one parameter rather than being split at spaces or commas.

const base = 'https://api.positionstack.com/v1';
const address = '1600 Pennsylvania Ave NW, Washington, DC';
console.log(`${base}/forward?query=${encodeURIComponent(address)}&access_key=YOUR_ACCESS_KEY`);

I ran the named JavaScript file request_urls.js with Node.js v26.7.0 to check how the query is encoded. Its exact output was:

https://api.positionstack.com/v1/forward?query=1600%20Pennsylvania%20Ave%20NW%2C%20Washington%2C%20DC&access_key=YOUR_ACCESS_KEY

YOUR_ACCESS_KEY is a placeholder, and the local run did not contact Positionstack. Supply the key from your application’s secret store. Use a URL library to encode user input instead of joining unescaped text into a query string.

Step 3: Build a reverse-geocoding request

Send the coordinate pair to the reverse endpoint when your application starts with a map point, device location, or stored coordinates. Use the same key-handling rule as the forward request.

const base = 'https://api.positionstack.com/v1';
const coords = '38.8977,-77.0365';
console.log(`${base}/reverse?query=${encodeURIComponent(coords)}&access_key=YOUR_ACCESS_KEY`);

The same local program generated this exact reverse URL:

https://api.positionstack.com/v1/reverse?query=38.8977%2C-77.0365&access_key=YOUR_ACCESS_KEY

A reverse lookup describes mapped features associated with the point. Preserve the original coordinates when the application needs to retain the observed point, such as a device location or a marker placed by a user.

Some mapping libraries write longitude before latitude, so compare the returned coordinates with the source point and inspect the request if they differ.

Step 4: Read the response and choose a candidate

Positionstack’s site shows a response organized under a data array, with fields such as latitude, longitude, type, address components, label, and sometimes a map URL. Inspect the actual response from your request because optional fields and the number of candidates can vary.

When several results arrive, compare the full label and components with the input and use the returned confidence information as one signal. Do not read a confidence value as a probability unless the provider documents that interpretation.

For a map marker, use the chosen result’s coordinates. For a form that needs a mailing address, inspect the address components and let the user confirm an ambiguous match. Keep the original query with the selected result when later review needs to explain how the application reached its choice.

Response-handling code should check whether the data field exists and contains a candidate before reading its properties. Handle malformed data or an API error without showing a stack trace or empty address to the user.

Parse the HTTP status before treating a response body as a successful lookup. An error response may have a different structure from the data array, so route it through error handling rather than reading it as a location result. Keep retries bounded and use a short delay between attempts when the failure may be temporary.

For an address field, decide whether your interface displays the provider’s full label or selected components such as street and locality. A full label can be suitable for a read-only result, while a form may need separate fields that the user can review. Keep the raw response available long enough to diagnose a mapping choice, but avoid retaining location data longer than the application needs.

Coordinate precision should follow the source and intended use. Rounding a point for display can be reasonable, but do not overwrite the source value if later calculations depend on it. Keep the representation used by the API separate from any shortened coordinate shown in the interface.

The request layer can return the parsed response or a clear error state. The application layer can then decide whether to show one candidate, ask the user to choose, or request a more specific query.

For a lookup that may take time, show a pending state and avoid sending the same request repeatedly while the first one is active. When users can edit an address, associate the response with the submitted query so a slow earlier answer does not replace a newer one. These are application-side safeguards and do not depend on a Positionstack-specific response field.

What should you check in a geocoding response?

Check that the response contains a usable candidate, that its address or coordinates match the intended place, and that your plan supports any optional feature you use. A successful HTTP exchange alone does not establish that a result is precise enough for your application.

Positionstack’s FAQ notes that map embedding depends on the subscription plan and that the response may include a map URL field. If it is absent, display the address without an embedded map.

The same FAQ describes batch requests using HTTP POST on Professional and higher plans. That is useful when an application processes a collection of locations, but it is a separate request mode from the single-query examples here. Confirm the account’s current plan and the current API documentation before building a batch workflow.

Positionstack’s FAQ describes worldwide coverage while noting that coverage quality differs between countries and locations. For address entry, delivery, or other consequential decisions, ask the person to confirm the selected result or validate it against an authoritative source.

Mapbox’s guide describes how its own results can differ by feature type and relevance. The result fields a provider returns determine what your application can display.

For related address lookup examples, see CodeForGeek’s forward and reverse Geocodeapi guide and address information lookup guide.

Positionstack’s FAQ also says an unsuccessful request that returns an error does not consume the monthly API request allowance. Check the response and account dashboard when troubleshooting instead of assuming every failed call has the same effect. Account limits and any overage terms should be checked in the live product information before deployment.

A timeout or server error means the request did not complete as expected, while an empty result means the provider answered but found no candidate for the submitted input. Use different, bounded recovery paths for those states.

For an address query, improve the text with components the user can verify, such as a city or postal code. Avoid silently changing a user’s spelling or adding a locality that the application cannot support. For coordinates, check that both values are present and within valid latitude and longitude ranges before making the request.

Logs help with later support. Record the submitted query, chosen candidate, and decision rule, while keeping the API key out of that record.

Use the response’s result type and address components to set a suitable detail threshold for deliveries or pickups, since a broad locality may fit a regional dashboard but not a driver at a building entrance.

Conclusion: keep geocoding decisions in your app

Choose the endpoint that matches the input. Keep the output tied to the user’s task, and use the official documentation and FAQ to confirm account-dependent details before shipping.

Positionstack’s official API documentation and FAQ cover parameters, formats, and account-dependent features. The local URL example does not make an authenticated API call, so verify live behavior with your own account before shipping an integration.

FAQ

These answers summarize the two request directions and the response limits covered above.