SDK libraries
Geocode from your backend with typed clients and optional provider fallbacks.
Choose a library for your server runtime, or use the framework-independent browser autocomplete client with a public origin-restricted token. Every SDK supports forward geocoding, reverse geocoding, address autocomplete with selection resolution, and optional Google and HERE providers.
Installation
The packages are not yet published to their registries. Install from the repository or a local artifact using the steps on each SDK page.
| Library | Package | Import / namespace |
|---|---|---|
| Node.js | @affordable-geo-apis/sdk | GeocodingClient |
| Python | affordable-geo-apis | affordable_geo_apis |
| PHP | affordable-geo-apis/sdk | AffordableGeoApis |
| C# / .NET | AffordableGeoApis (local project) | AffordableGeoApis |
Available operations
| Operation | Node.js / PHP | Python | C# |
|---|---|---|---|
| Address to coordinates | geocode | geocode | GeocodeAsync |
| Free-text search | search | search | SearchAsync |
| Coordinates to address | reverseGeocode | reverse_geocode | ReverseGeocodeAsync |
| Suggest addresses | autocomplete | autocomplete | AutocompleteAsync |
| Resolve selected suggestion | resolveAutocomplete | resolve_autocomplete | ResolveAutocompleteAsync |
Geocode, search, and reverse geocode return normalized results (id, label, type, house number, street, city, state, ZIP, country, coordinates, confidence, match type, source, provider), the selected provider, and an attempt history. Request field names (street, q, lat, lon, near) are the same in all languages; SDK-only options use each language's naming conventions.
Autocomplete returns labeled suggestions and an attempt history. Its country is required and must be recognized. Selection resolution returns one normalized address with coordinates, without a response envelope or provider-chain history. See the autocomplete guide.
Provider selection
For geocode, search, and reverse geocode, the SDK calls primary first for Canada, the United States, and Mexico, or when no country hint is supplied. Other nonempty hints route to configured backups. Autocomplete requires a recognized country and restricts primary suggestions to CA/US/MX; other recognized countries route to backups.
Primary results are kept if any candidate reaches the confidence threshold, which defaults to 0.8. Otherwise, configured fallbacks run in order; the first nonempty backup wins. Eligible outages can also trigger fallback.
Autocomplete selects the first nonempty suggestion response without confidence scoring. Resolution calls only the selected suggestion's provider and does not try backups, reserve fallback budget, or use circuit breakers. Timeouts and caller cancellation still apply.
Backups are disabled until you supply provider credentials. Calls use your own Google/HERE account and quota. Use a fallback budget to cap backup calls on one client.
Configuration
All SDKs provide a ten-second per-provider timeout, caller cancellation or deadlines, optional fallback budgets, and per-provider circuit breakers. They do not automatically retry, cache, or merge results.
Node.js and PHP use camelCase option names; Python uses snake_case; C# uses PascalCase. See the client reference for TypeScript, Python, or PHP.
The browser client exposes autocomplete and selection resolution, with primary coverage for CA/US/MX and optional direct Google/HERE fallbacks using public provider keys. The server SDKs retain full operations and optional fallbacks; Python and PHP are backend integrations. Browser HTTP 403 origin denials are terminal across TypeScript, both Python clients, PHP and C#.
C# uses PascalCase properties and GeocodeAsync, SearchAsync, ReverseGeocodeAsync, AutocompleteAsync, and ResolveAutocompleteAsync. It accepts CancellationToken, uses millisecond timeouts, and exposes MaxFallbackRequests for the per-client backup budget. See the .NET reference.