Getting Started

Each Positionstack account is assigned a unique API access key used to authenticate all geocoding and reverse geocoding requests.
You can find your personal key by logging in to your Positionstack Dashboard.

API Access Key & Authentication

To start using the API, include your access_key as a query parameter in every request.
Here’s a basic example of a forward geocoding request:

Note: You must sign up for an account to obtain your API access key.

Important: Always keep your API access key private. Treat it like a password — do not share it publicly or embed it in client-side code.
If you believe your key has been compromised, you can revoke and generate a new key at any time from your account dashboard.

256-bit HTTPS Encryption

All API requests are secured using 256-bit HTTPS encryption — available on all plans.
Always use https:// when making requests to ensure data integrity and privacy.

Example

JSONP Callbacks

The Positionstack API supports JSONP callbacks, allowing you to integrate directly into browser-based applications.
To enable JSONP, append a callback parameter to your request URL and set it to your desired function name.

Example Request:

Example Response:

The API also supports Access-Control (CORS) headers for modern web integration

API Errors

If a request fails, the API returns an error object containing details about the issue.
Each error includes a code, message, and optionally a context object for additional information.

Example Error:

HTTP Status Codes:

• 200 – Success
• 422 – Unprocessable Entity (validation error)

Common API Error Codes

Important: API errors are always returned in JSON format, regardless of which output format you may have chosen using the API's output parameter.