gRPC

The JSON POST endpoints and native gRPC use our public platform protobuf contract. The edge translates this contract to the geocoder’s internal API; backend fields and RPC names are not the public contract.

Native gRPC clients

Use the protobuf contract to generate a standard gRPC client. Call opengeocoding.v1.OpenGeocoding with x-api-key or authorization: Bearer <key> metadata. All six methods are unary:

JSON alias	gRPC method
`/v1/search`	`Search`
`/v1/autocomplete`	`Autocomplete`
`/v1/retrieve`	`Retrieve`
`/v1/reverse`	`Reverse`
`/v1/regions`	`Regions`
`/v1/resolve-region`	`ResolveRegion`

Canonical gRPC paths are /opengeocoding.v1.OpenGeocoding/<Method>, on the same host and port as the JSON API. The OpenAPI specification describes the HTTP JSON API; use the protobuf contract for gRPC code generation.

With grpcurl, from the repository root against a local edge:

grpcurl -plaintext -import-path edge/proto -proto platform-v1.proto   -H 'x-api-key: og_...' -d '{"addressString":"Copenhagen"}'   localhost:8080 opengeocoding.v1.OpenGeocoding/Search

Use TLS instead of -plaintext in production. The ingress must forward HTTP/2 to the edge (h2c internally) and preserve gRPC metadata and trailers. Do not connect to the geocoder pods directly: that bypasses authentication and metering.

Transport limits

The edge accepts application/grpc and application/grpc+proto. Requests may be gzip-compressed; replies are uncompressed. Request messages are capped at 64 KiB before and after decompression, replies at 16 MiB. grpc-timeout is honored up to a 10-second server limit. Streaming, gRPC-Web and server reflection are not supported; supply the proto to tools such as grpcurl.

Status and billing

A gRPC HTTP 200 can still be an error. Only successful billable operations with grpc-status: 0 spend a credit. Autocomplete and Regions consume no credits, even at zero balance, but remain authenticated and share the account rate limit. Autocomplete returns no coordinates or bounding boxes; call Retrieve with a selected opaque ID for its location. Server-returned errors such as UNAUTHENTICATED (16), INVALID_ARGUMENT (3), NOT_FOUND (5), DEADLINE_EXCEEDED (4), RESOURCE_EXHAUSTED (8) or UNAVAILABLE (14) do not spend credits. JSON and gRPC share the account’s credits and rate limit.

Completed replies are charged when prepared, before network delivery. Disconnecting during delivery does not refund completed work. See credits and rate limits.

Attribution

Results contain data © OpenStreetMap contributors (ODbL), the Overture Maps Foundation, OpenAddresses contributors and GeoNames (CC BY 4.0). Credit them where you show results.