Lookup

Geo Controller IP Lookup API allows external applications to retrieve geographic information about an IP address using an authenticated HTTP request.

The lookup endpoint returns geographic data in JSON format, including available country, region, city, continent, timezone, currency, and other IP-related properties.

To access this endpoint, your application must provide a valid API Key and an Access Token generated through the Geo Controller authentication endpoint.

License requirement: Public API access requires an active Geo Controller Business License.

1. Available API Endpoints

Geo Controller supports two API transport modes: WordPress AJAX and WordPress REST API.

These modes are mutually exclusive. Only the endpoint corresponding to the currently selected mode is registered.

WordPress AJAX Endpoint

The legacy AJAX transport uses the standard WordPress AJAX handler:

https://yourdomain.com/wp-ajax.php?action=cf_geoplugin_lookup

The action parameter must be set to cf_geoplugin_lookup.

WordPress REST API Endpoint

When the REST transport is enabled, use the native WordPress REST API route:

https://yourdomain.com/wp-json/cf-geoplugin/v1/lookup

The REST endpoint does not require an action parameter.

Important: Changing the API transport mode changes which endpoint is available. Existing integrations must use the endpoint corresponding to the selected mode.

2. Request Parameters

Both transports accept GET and POST requests. The following parameters are supported:

Note: Although the route does not enforce the ip parameter as required at the WordPress REST argument-validation level, external applications should explicitly supply a valid IP address to avoid ambiguity about the lookup target.

For consistent behavior, always provide the API Key, Access Token, and target IP address.

3. Authentication Requirements

Before performing a lookup, your application must authenticate with Geo Controller and obtain an Access Token.

The authentication process requires:

• A valid Geo Controller API Key.
• The Secret API Key configured in Geo Controller.
• An application name identifying the external integration.

After successful authentication, Geo Controller returns an Access Token that can be used for subsequent lookup requests.

The lookup endpoint verifies the supplied API Key and checks the Access Token against the tokens stored for the current Secret API Key.

For complete instructions, see REST API Authentication.

4. Example: WordPress AJAX Lookup

The following example performs a lookup using the legacy AJAX transport.

Replace the example domain, API Key, and Access Token with your own credentials.

curl --request POST \
  'https://yourdomain.com/wp-ajax.php' \
  --data-urlencode 'action=cf_geoplugin_lookup' \
  --data-urlencode 'api_key=YOUR_API_KEY' \
  --data-urlencode 'access_token=YOUR_ACCESS_TOKEN' \
  --data-urlencode 'ip=8.8.8.8' \
  --data-urlencode 'base_currency=USD'

Geo Controller validates the credentials and performs the requested geographic lookup.

5. Example: WordPress REST API Lookup

When the REST transport is enabled, the same lookup can be performed through the native WordPress REST API.

curl --request POST \
  'https://yourdomain.com/wp-json/cf-geoplugin/v1/lookup' \
  --data-urlencode 'api_key=YOUR_API_KEY' \
  --data-urlencode 'access_token=YOUR_ACCESS_TOKEN' \
  --data-urlencode 'ip=8.8.8.8' \
  --data-urlencode 'base_currency=USD'

Unlike the AJAX request, the REST request does not require an action parameter.

Both transport modes use the same underlying Geo Controller lookup logic.

6. Example JSON Response

A successful request returns a JSON object containing the available geographic lookup information and the API response status.

The following example illustrates the response structure. Geographic values are representative and may differ depending on the requested IP address, lookup provider, and available data.

{
  "ip": "8.8.8.8",
  "country_code": "US",
  "country": "United States",
  "region": "California",
  "city": "Mountain View",
  "continent": "North America",
  "continent_code": "NA",
  "timezone": "America/Los_Angeles",
  "currency": "USD",
  "base_currency": "USD",
  "error": false,
  "error_message": null,
  "code": 200
}

This is an abbreviated example, not an exhaustive response schema. Actual geographic properties and values depend on the underlying lookup result.

The IP address and location are used only to demonstrate the JSON structure and should not be treated as a verified current geolocation result.

7. Understanding the Response

The lookup response contains geographic information alongside fields indicating the outcome of the API request.

Additional fields may include IP-related information, coordinates, geographic identifiers, currency conversion data, timestamps, and other values provided by Geo Controller.

Important: The successful API handler response uses code: 200. The underlying geographic dataset may contain additional properties, but the authenticated endpoint sets its own final API status fields.

8. Error Responses

Geo Controller validates the API Key and Access Token before performing the lookup.

Invalid credentials return an HTTP 400 Bad Request response with a JSON error object.

Invalid API Key

{
  "error": true,
  "code": 400,
  "error_message": "API key is invalid."
}

Invalid Access Token

{
  "error": true,
  "code": 400,
  "error_message": "Access token is invalid."
}

These examples show the relevant error fields. Additional response properties may be present depending on the handler.

Insufficient License

The public API requires a Business License.

In AJAX mode, requests made without the required license receive a license-related JSON error with HTTP status 400.

In REST mode, public routes are not registered when the required license level is unavailable. WordPress may therefore return a route-not-found response instead of the AJAX license error.

9. Using the Lookup API in PHP

The following example demonstrates how an external PHP application can perform a lookup using the WordPress REST transport.

<?php

$endpoint = 'https://yourdomain.com/wp-json/cf-geoplugin/v1/lookup';

$payload = [
    'api_key'       => 'YOUR_API_KEY',
    'access_token'  => 'YOUR_ACCESS_TOKEN',
    'ip'            => '8.8.8.8',
    'base_currency' => 'USD',
];

$ch = curl_init($endpoint);

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/x-www-form-urlencoded',
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error    = curl_error($ch);

curl_close($ch);

if ($response === false || $error !== '') {
    // Handle the transport error.
} else {
    $data = json_decode($response, true);

    if (
        $status === 200
        && is_array($data)
        && ($data['error'] ?? true) === false
    ) {
        $country = $data['country'] ?? '';
        $city    = $data['city'] ?? '';
    } else {
        // Handle the API error.
    }
}

Store API credentials securely in your application’s server-side configuration. Do not hardcode production credentials in publicly accessible files.

10. Access Token Usage

Each successful authenticated lookup increments the usage counter associated with the Access Token.

Administrators can review registered applications and token usage in the Geo Controller REST API settings.

Access Tokens are associated with the configured Secret API Key. Generating a new Secret API Key invalidates previously issued Access Tokens.

If a lookup begins returning an invalid-token error after credentials have been changed, authenticate again to obtain a new Access Token.

11. Performance and Caching

Geographic lookups can involve additional processing and external service requests. Repeatedly requesting the same IP address may increase response times and unnecessary lookup activity.

For better performance:

• Cache lookup results in your application when appropriate.
• Use a cache expiration policy suitable for your use case.
• Avoid requesting the same IP address repeatedly during a single operation.
• Handle network timeouts and temporary API failures.
• Use asynchronous or background processing for large batches of IP addresses.
• Review your license and any applicable geolocation service limitations.

The appropriate cache duration depends on the application’s requirements and the acceptable age of geographic data.

IP geolocation information can change over time, so cached results should not be considered permanent.

12. Security Recommendations

The Lookup API is intended for authenticated integrations. Protect the credentials used to access it.

• Use HTTPS: Always send API requests over an encrypted connection.
• Prefer POST: Avoid placing API Keys and Access Tokens in URL query strings, where they may appear in logs or browser history.
• Protect Access Tokens: Treat tokens as credentials and do not expose them in public JavaScript.
• Validate IP addresses: Validate externally supplied IPv4 and IPv6 addresses before submitting lookup requests.
• Handle errors: Check HTTP status codes and JSON error fields before using the response.
• Respect privacy: Process and retain IP addresses only when necessary and in accordance with applicable privacy requirements.

Important: IP-based geolocation is approximate. VPNs, proxies, mobile networks, and geolocation database inaccuracies can affect the detected location.

Do not treat a successful geographic lookup as proof of a person’s identity or physical presence.

13. Troubleshooting

Endpoint Returns 404

Confirm that the correct API transport mode is enabled.

The native REST route is available only when REST transport is selected and the required Business License is active.

Also verify that the WordPress REST API is accessible and that your server or security configuration is not blocking the request.

API Key Is Invalid

Verify that the supplied API Key matches the value configured in Geo Controller.

Check that your application is connecting to the correct WordPress installation.

Access Token Is Invalid

Confirm that the token was generated for the current Geo Controller installation.

If the Secret API Key was regenerated, authenticate again to obtain a new token.

Lookup Returns Unexpected Geographic Data

Check the requested IP address and confirm that it is a valid IPv4 or IPv6 address.

Geolocation results depend on the available geographic database and lookup provider. Some properties may be missing, approximate, or outdated.

Lookup Requests Are Slow

Review server connectivity, geographic lookup processing, and application caching.

Consider caching repeated lookup results and avoiding unnecessary synchronous requests.

Related Documentation

• REST API Authentication
• PHP Integration
• JavaScript Integration

Summary: The Geo Controller Lookup API allows authenticated external applications to retrieve geographic information for an IP address. Use the endpoint corresponding to your selected API transport mode, authenticate with a valid API Key and Access Token, and handle geographic data, errors, and caching appropriately.