How to Generate Geoapify API Clients and SDKs from OpenAPI

Generate a typed API client from OpenAPI

You need repeatable client code for a Geoapify API and want request models and operation methods to follow its published contract. An OpenAPI code generator reads the operation IDs, schemas, parameters, authentication methods, and server URLs in a specification and turns them into language-specific API classes and models.

Popular choices include OpenAPI Generator, Swagger Codegen, and generators built into API clients or IDEs. This guide uses the community-maintained OpenAPI Generator through its npm wrapper:

npx @openapitools/openapi-generator-cli

The wrapper downloads and runs the OpenAPI Generator Java archive. Install Node.js and npm, and make Java 11 or newer available on PATH before running it. The first invocation can take longer while the generator is downloaded.

The examples use the focused Forward Geocoding API specification and generate TypeScript, Python, Java, or C# client projects. Pick the generator that matches the application's language and HTTP stack; generating every target usually adds maintenance without adding value.

Task flow: focused OpenAPI URL → generator configuration → isolated generated directory → application wrapper.

Generated clients are project artifacts, not separately supported Geoapify SDK releases. Review the generated runtime, serialization, dependencies, and authentication interface before adopting it. Pin the generator version in the generated openapitools.json file, and regenerate from the canonical specification when the API contract changes instead of hand-editing generated files.

Use OpenAPI Generator through npx

Run OpenAPI Generator through the npm wrapper so the project does not need a global CLI installation:

npx @openapitools/openapi-generator-cli generate \
  -i <OPENAPI_URL_OR_FILE> \
  -g <GENERATOR_NAME> \
  -o <OUTPUT_DIRECTORY>

The command has one subcommand followed by generation parameters:

List the available generators and inspect the options for one target before choosing additional properties:

npx @openapitools/openapi-generator-cli list
npx @openapitools/openapi-generator-cli config-help -g typescript-fetch

The npm wrapper stores its selected generator version in openapitools.json. Commit that configuration with the generation command so local and CI builds use the same generator release. Generated output can still change when the specification, generator version, or generator-specific properties change.

OpenAPI Generator runs on Java. If the command fails with a Java class-version error, update the JDK available on PATH to Java 11 or newer before retrying.

Generate a TypeScript client

Use typescript-fetch for a typed client built on the standard Fetch API. The additional properties add npm package metadata and request modern JavaScript output:

npx @openapitools/openapi-generator-cli generate \
  -i https://apidocs.geoapify.com/assets/openapi/specs/forward-geocoding/forward-geocoding-api-openapi-specs.json \
  -g typescript-fetch \
  -o generated/geoapify-forward-geocoding-typescript \
  --additional-properties=npmName=@example/geoapify-forward-geocoding,npmVersion=1.0.0,supportsES6=true

Replace the example npm scope with one owned by the project. Inspect the generated README.md, package.json, API classes, models, and runtime before installing the package. The generated package is application-owned code; it is not an official @geoapify SDK.

The selected specification supplies the ForwardGeocodingApi class and forwardGeocode operation name. A different generator release can format those names differently, so use the generated README and the TypeScript compiler as the final source of truth.

Generate a Python client

Use the python generator for typed models, API classes, package metadata, and usage documentation suitable for a Python application:

npx @openapitools/openapi-generator-cli generate \
  -i https://apidocs.geoapify.com/assets/openapi/specs/forward-geocoding/forward-geocoding-api-openapi-specs.json \
  -g python \
  -o generated/geoapify-forward-geocoding-python

Open the generated README.md for the exact build, local-install, authentication, and method names produced by the pinned generator version. Keep application configuration and response mapping in a handwritten module outside the generated directory so regeneration does not overwrite them.

Generate a Java client

Use the java generator when a JVM application needs typed API operations and models:

npx @openapitools/openapi-generator-cli generate \
  -i https://apidocs.geoapify.com/assets/openapi/specs/forward-geocoding/forward-geocoding-api-openapi-specs.json \
  -g java \
  -o generated/geoapify-forward-geocoding-java

The Java generator supports several HTTP libraries and build settings. Run config-help -g java, select the library that matches the application, and place stable choices in a checked-in JSON or YAML config file passed with -c. Inspect the generated build file and runtime dependencies before adding the client as an application module.

Generate a C# client

Use the csharp generator for a typed client library consumed by a .NET application:

npx @openapitools/openapi-generator-cli generate \
  -i https://apidocs.geoapify.com/assets/openapi/specs/forward-geocoding/forward-geocoding-api-openapi-specs.json \
  -g csharp \
  -o generated/geoapify-forward-geocoding-csharp

Run config-help -g csharp to review the supported target frameworks, package settings, and HTTP-library options for the pinned generator release. Keep the generated project isolated, build it with the .NET version used by the application, and put Geoapify configuration in an application-owned service rather than generated classes.

Integrate and maintain the generated SDK

The following server-side TypeScript example builds the typescript-fetch output from the previous section and installs it into an application as a local package:

cd generated/geoapify-forward-geocoding-typescript
npm install
npm run build
cd ../..
npm install ./generated/geoapify-forward-geocoding-typescript

Follow the generated README.md if the pinned generator version provides different build scripts. Then place a handwritten service outside the generated directory:

import {
  Configuration,
  ForwardGeocodingApi
} from "@example/geoapify-forward-geocoding";

const apiKey = process.env.GEOAPIFY_API_KEY;

if (!apiKey) {
  throw new Error("GEOAPIFY_API_KEY is not configured");
}

const geocodingApi = new ForwardGeocodingApi(new Configuration({
  basePath: "https://api.geoapify.com/v1",
  headers: { "x-api-key": apiKey }
}));

export async function geocodeAddress(text: string) {
  const response = await geocodingApi.forwardGeocode({ text, limit: 1 });
  const feature = response.features[0];

  if (!feature) {
    return null;
  }

  return {
    formatted: feature.properties.formatted,
    latitude: feature.properties.lat,
    longitude: feature.properties.lon
  };
}

The wrapper owns the API key, base URL, application input, empty-result behavior, and returned result shape. The API key comes from runtime configuration and is sent in the x-api-key header; it is not written into generated code. Create a key in Geoapify MyProjects. For browser applications, restrict the key to the application's allowed origins.

The class and method names are derived from the specification's tag and operation ID. If the pinned generator emits different names or authentication helpers, follow its generated README and adapt only the handwritten service.

Call the service with the user's address and handle an empty result explicitly:

const result = await geocodeAddress("Alexanderplatz, Berlin, Germany");

if (!result) {
  console.log("No matching address found");
} else {
  console.log(result.formatted, result.latitude, result.longitude);
}

Make regeneration repeatable

Keep the complete command in the application's package.json:

{
  "scripts": {
    "generate:geoapify-client": "openapi-generator-cli generate -i https://apidocs.geoapify.com/assets/openapi/specs/forward-geocoding/forward-geocoding-api-openapi-specs.json -g typescript-fetch -o generated/geoapify-forward-geocoding-typescript --additional-properties=npmName=@example/geoapify-forward-geocoding,npmVersion=1.0.0,supportsES6=true"
  },
  "devDependencies": {
    "@openapitools/openapi-generator-cli": "<PINNED_VERSION>"
  }
}

Install and pin the actual CLI version used by the project, commit openapitools.json, and regenerate into a clean directory when the specification changes. Review the generated diff, run the package build, and run a focused application integration test before merging.

Keep these boundaries in the handwritten layer:

• Preserve the input alternatives defined by the specification. For example, forward-geocoding free-text and structured address inputs should not be sent together.
• Handle non-success responses, empty feature collections, timeouts, and cancellation in the handwritten layer.
• Add a focused integration test using a known address, but never record the API key in fixtures or snapshots.
• Treat generated dependencies like other dependencies: review security and compatibility updates instead of assuming regeneration updates them safely.