Postali Getting Started: API Keys & First Geocoding Request

Getting started overview

To begin using Postali's geospatial APIs, the initial steps involve setting up an account, obtaining API credentials, and then executing a basic request. Postali provides APIs for services such as geocoding and address validation, which are accessed via a RESTful interface using an API key for authentication. The platform supports various programming languages through official SDKs, including JavaScript and Python, making integration into different development environments feasible. This guide focuses on the Geocoding API as a primary example for a first request.

The process is summarized in the table below:

Create an account and get keys

Access to Postali's APIs requires an authenticated account and an API key. This key serves as a credential to authorize your requests and link them to your usage plan, which includes a free tier offering 2,500 requests per day.

Sign-up Process

1. Navigate to the Postali sign-up page.
2. Provide the required information, typically an email address and a password.
3. Complete any necessary email verification steps.

Locating Your API Key

Upon successful account creation and login, your API key will be available in your Postali dashboard.

1. Log in to your Postali account dashboard.
2. Look for a section labeled "API Keys" or "Credentials."
3. Your unique API key will be displayed there. Copy this key securely, as it will be required for every API request you make. Postali's authentication documentation provides further details on managing API keys.

It is crucial to handle your API key securely to prevent unauthorized use. Best practices for API key security often recommend storing keys as environment variables rather than embedding them directly in source code, especially for client-side applications where they could be exposed. For server-side applications, securing the environment where keys are stored is also vital, as detailed in general API key best practices from Google Cloud.

Your first request

This section will guide you through making your first geocoding request using the Postali Geocoding API. The API is RESTful and accepts HTTP GET requests to a specific endpoint, returning data in JSON format.

API Endpoint

The base endpoint for the Geocoding API is https://api.postali.co/v1/geocode. You will append query parameters to this URL to specify the address you want to geocode and to include your API key.

Request Parameters

• address (required): The address string to be geocoded (e.g., "1600 Amphitheatre Pkwy, Mountain View, CA").
• api_key (required): Your unique Postali API key.

Example cURL Request

A simple way to test the API is using curl from your terminal:

curl "https://api.postali.co/v1/geocode?address=1600%20Amphitheatre%20Pkwy,%20Mountain%20View,%20CA&api_key=YOUR_API_KEY"

Replace YOUR_API_KEY with the actual key you obtained from your dashboard. The %20 represents a URL-encoded space character.

Example Python Request

Using the requests library in Python:

import requests

api_key = "YOUR_API_KEY"
address = "1600 Amphitheatre Pkwy, Mountain View, CA"

url = f"https://api.postali.co/v1/geocode?address={address}&api_key={api_key}"
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print("Latitude:", data['results'][0]['geometry']['location']['lat'])
    print("Longitude:", data['results'][0]['geometry']['location']['lng'])
else:
    print(f"Error: {response.status_code} - {response.text}")

Remember to install the requests library if you haven't already: pip install requests.

Example JavaScript Request (Node.js)

Using the fetch API in a Node.js environment:

const fetch = require('node-fetch'); // For Node.js; not needed in browser environments

const apiKey = "YOUR_API_KEY";
const address = "1600 Amphitheatre Pkwy, Mountain View, CA";

async function geocodeAddress() {
  const url = `https://api.postali.co/v1/geocode?address=${encodeURIComponent(address)}&api_key=${apiKey}`;
  try {
    const response = await fetch(url);
    const data = await response.json();

    if (response.ok) {
      console.log("Latitude:", data.results[0].geometry.location.lat);
      console.log("Longitude:", data.results[0].geometry.location.lng);
    } else {
      console.error(`Error: ${response.status} - ${data.message}`);
    }
  } catch (error) {
    console.error("Fetch error:", error);
  }
}

geocodeAddress();

In a browser environment, you would not need require('node-fetch'). The fetch API is natively available. Ensure you replace YOUR_API_KEY.

Expected Response

A successful geocoding request will typically return a JSON object similar to this, containing location details:

{
  "status": "OK",
  "results": [
    {
      "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "geometry": {
        "location": {
          "lat": 37.4220656,
          "lng": -122.0840897
        },
        "location_type": "ROOFTOP",
        "viewport": {
          "northeast": {
            "lat": 37.4234145802915,
            "lng": -122.0827407197085
          },
          "southwest": {
            "lat": 37.4207166197085,
            "lng": -122.0854386802915
          }
        }
      },
      "place_id": "ChIJf7L0iA-6j4AR27fQ1S2S4eQ",
      "types": ["street_address"]
    }
  ]
}

The lat and lng values within the geometry.location object represent the latitude and longitude coordinates of the geocoded address.

Common next steps

Once you have successfully made your first request, you can explore more advanced features and integrations:

• Explore other APIs: Postali offers Reverse Geocoding, Address Validation, and Timezone APIs. Refer to the Postali documentation for detailed usage.
• Integrate SDKs: For more streamlined development, consider using one of the official Postali SDKs available for languages like JavaScript, Python, PHP, Ruby, Go, Java, and C#. These SDKs abstract away HTTP request handling and JSON parsing.
• Monitor usage: Keep an eye on your API request usage through your Postali dashboard to stay within your free tier limits or manage paid plan consumption.
• Error handling: Implement robust error handling in your application to gracefully manage scenarios such as invalid API keys, rate limits, or malformed requests. Postali's API Error documentation provides common error codes and their meanings.
• Optimize requests: For applications requiring high volumes of requests, consider strategies like batch geocoding (if supported) or caching results for frequently requested addresses to reduce API calls and improve performance.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some common problems and their solutions:

• 401 Unauthorized or Invalid API Key:
  • Issue: Your API key is incorrect, missing, or has not been properly activated.
  • Solution: Double-check that you have copied the API key exactly from your Postali dashboard. Ensure there are no leading or trailing spaces. Verify that the key is included as the api_key query parameter in your request.
• 400 Bad Request or Missing Required Parameter:
  • Issue: A required parameter, such as address for the Geocoding API, is missing or malformed.
  • Solution: Ensure all mandatory parameters are present and correctly formatted. For addresses, ensure proper URL encoding for special characters and spaces.
• 403 Forbidden or Quota Exceeded:
  • Issue: You have exceeded your daily request limit or your account plan does not permit the requested operation.
  • Solution: Check your usage statistics in the Postali dashboard usage section. If you've reached your free tier limit, consider upgrading to a paid plan or waiting for your quota to reset.
• Network issues:
  • Issue: Your request fails due to connectivity problems.
  • Solution: Verify your internet connection. If you are behind a firewall or proxy, ensure it allows outbound connections to api.postali.co.
• Incorrect JSON parsing:
  • Issue: Your code fails to process the API response correctly.
  • Solution: Review the Postali Geocoding API response structure documentation carefully. Ensure your JSON parsing logic correctly navigates the nested objects to access fields like lat and lng.

For more detailed troubleshooting, consult the Postali official documentation or contact Postali support if problems persist.