How to Use Geoapify OpenAPI with AI Coding Tools

Give an AI coding tool the API contract and the task

You want an AI coding tool to implement a Geoapify integration without guessing endpoint paths, parameter names, coordinate order, or response fields. Give it the focused OpenAPI specification as the machine-readable contract and separately describe the application outcome.

For example, the task might accept a postal address, call Forward Geocoding, and return the best result's formatted address, latitude, and longitude. The OpenAPI document defines the HTTP contract; your task defines user experience, state management, security, and verification.

Task flow: focused OpenAPI contract + application requirements → generated change → tests and contract review.

Follow this workflow:

1. Choose the focused specification that owns the required operation.
2. Give the AI tool access to the unchanged specification and relevant human-readable documentation.
3. Define the runtime, inputs, expected output, security model, error behavior, and test requirements.
4. Ask the tool to inspect the existing application and explain its implementation plan before editing.
5. Generate the smallest change that follows the application's existing architecture.
6. Compare the request and response mapping with the OpenAPI contract, then run the relevant tests and build.

Do not provide an API key in a prompt, attached specification, example URL, fixture, or generated test. For server-side code, read it from runtime secrets and prefer the x-api-key header. A key included in browser code is visible after bundling, even when it originated in an environment variable, so restrict browser keys to the application's allowed origins.

Choose and provide only the required specification

Step 1: Select the focused API contract

Open the Geoapify OpenAPI catalog and select the focused API that owns the desired operation. For address-to-coordinate tasks, provide:

https://apidocs.geoapify.com/assets/openapi/specs/forward-geocoding/forward-geocoding-api-openapi-specs.json

Focused specifications reduce context size and make operation selection clearer. Do not give an AI tool every Geoapify specification when the implementation needs only one API.

Step 2: Give the tool access to the specification

Choose the delivery method that matches the AI tool's capabilities:

Do not assume that a URL has been read successfully. Ask the tool to report the operation ID, endpoint, and relevant response schema it found before implementation. Treat the specification as read-only: the tool may use it to generate or verify application code, but it must not modify the contract to make incorrect code appear valid.

Step 3: Add application context

Provide these inputs together:

• The canonical specification URL or unchanged downloaded specification.
• The relevant human-readable documentation page.
• The application's framework, HTTP client, state-management, and testing conventions.
• Exact user inputs and expected application output.
• Security constraints for browser or server-side API-key use.
• Required empty, error, loading, cancellation, and cleanup behavior.
• Whether the tool may add dependencies, create files, or change public interfaces.

Tell the tool that the specification is authoritative for request and response fields. Ask it to inspect the existing repository conventions, identify the files it expects to change, and explain its request flow before editing. It should stop and report a mismatch rather than inventing an undocumented parameter, silently changing the contract, or rewriting unrelated code.

Prompt the implementation

The following task is concrete enough for an AI coding tool to implement and for a reviewer to verify. It targets a server-side TypeScript application; replace the framework and test commands with those used by the project.

Implement server-side address-to-coordinate lookup in this existing TypeScript application.

Source of truth:
- Read the Geoapify Forward Geocoding OpenAPI specification:
  https://apidocs.geoapify.com/assets/openapi/specs/forward-geocoding/forward-geocoding-api-openapi-specs.json
- Treat the specification as read-only. Do not modify or replace it.
- Before editing, inspect the existing application and report the operation ID,
  endpoint, relevant response schema, proposed request flow, and files to change.
- Stop and report any mismatch instead of inventing fields or parameters.

Scope:
- Follow the project's existing HTTP, configuration, service, and testing patterns.
- Do not add a dependency unless the existing stack cannot perform the request;
  explain any required dependency before adding it.
- Preserve unrelated code and public interfaces.

Request:
- Accept one complete postal address as a string.
- Use the forwardGeocode operation with the free-text `text` parameter.
- Request `limit=1` and `format=geojson`.
- Do not send structured address parameters together with `text`.
- Read GEOAPIFY_API_KEY from runtime secrets and send it in the `x-api-key` header.
- Never hard-code, log, return, or commit the key or a credential-bearing URL.

Result:
- Return the first feature as this application-owned shape, or null when no
  feature exists:

  type GeocodingResult = {
    formatted: string;
    latitude: number;
    longitude: number;
  } | null;

- Map formatted, latitude, and longitude only from fields documented by the
  GeoJSON response schema.

Behavior:
- Validate an empty address before sending the request.
- Handle 400, 401, 429, 500, network failure, timeout, cancellation, and an
  empty feature collection without exposing credentials or internal details.
- Do not automatically retry 400 or 401. Do not retry 429 without an explicit,
  bounded backoff policy.
- Prevent an older response from replacing the result of a newer request when
  the surrounding application can issue concurrent searches.

Verification:
- Mock the HTTP boundary in automated tests; do not require a real API key.
- Test request construction, successful response mapping, no results, request
  failure, and cancellation.
- Compare every endpoint, parameter, authentication field, and accessed response
  property with the OpenAPI specification.
- Run the relevant tests and build. Report changed files, commands, results,
  assumptions, and any remaining risks.

For a browser integration, replace the server authentication instructions. State explicitly that the key will be present in the delivered application, load it through the project's public runtime or build configuration, and restrict it in Geoapify to the application's allowed origins. Do not describe a browser environment variable as a secret.

If the tool supports a separate planning phase, approve the plan only after it identifies forwardGeocode, GET /geocode/search, and the GeoJSON response fields required by the result type.

Verify the generated integration

OpenAPI reduces guessing, but it does not prove that generated code uses the contract correctly. Compare the implementation with this checklist before accepting it:

Also review behavior that OpenAPI cannot validate:

• Loading and error messages are accessible and useful without revealing request URLs or credentials.
• A stale response cannot overwrite a newer search result.
• Retry behavior is bounded and does not amplify rate limiting.
• New dependencies are necessary, maintained, and consistent with the application.
• The change preserves existing architecture, cleanup behavior, and unrelated files.

If the generated request does not match the contract, give the tool a narrow correction task:

The generated request does not match the provided Geoapify Forward Geocoding
OpenAPI contract.

Compare the implementation with the forwardGeocode operation. List every
mismatch before editing. Change only request construction, response mapping,
and the directly affected tests. Do not invent parameters, modify the OpenAPI
specification, expose the API key, or rewrite unrelated code.

After the correction, run the focused tests and build, then report the exact
contract fields used and any remaining assumptions.

When the focused Geoapify specification changes, repeat the contract comparison and automated tests. Keep the specification URL or local source path with the implementation task so a future update can be reviewed against the same source of truth.