Ctrlk
Log inGet startedAsk Navixy AI
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Geocoder

Turn an address into map locations, and a location back into an address.

The geocoder converts between addresses and coordinates. geocoder/search_address takes an address and returns the locations that match it, most relevant first. geocoder/search_location takes a coordinate pair and returns the address at that point.

The two directions overlap in one place: a q value that is two decimal numbers separated by a comma, such as 37.825014,-122.372020, is read as a coordinate pair, so geocoder/search_address performs a reverse lookup instead and returns a single result. Both numbers must carry a decimal point for that to happen.

Each request names the provider it wants in its geocoder parameter. Accounts with premium GIS always use Google, whatever the request asks for.

API actions

API base path: /geocoder.

Operations that list no errors of their own return only the general error codes.

Search address

post
/geocoder/search_address

Forward geocoding: return the locations matching an address, most relevant first.

A coordinate pair in q is handled as reverse geocoding instead. When q is two decimal numbers separated by a comma, such as 37.825014,-122.372020, it is read as latitude and longitude and the address at that point is returned as a single result. Both numbers must carry a decimal point for this to trigger.

Returns error 210 when nothing matches.

Authorizations
AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body
qstring · min: 1Required

Address, place name, or a lat,lng coordinate pair. Trimmed of surrounding whitespace and cannot be empty.

geocoderstring · enumOptional

Optional. Preferred geocoder. Accounts with premium GIS always use Google regardless of this value.

Possible values:
langstring · max: 5Optional

Optional. ISO 639 language code for the result, at most 5 characters, for example en or en_US. Defaults to the session language.

with_detailsbooleanOptional

Optional. Default false. Include the parsed details object in the response.

Responses
200

Matching locations

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
post/geocoder/search_address
POST /v2/geocoder/search_address HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 123

{
  "q": "text",
  "geocoder": "google",
  "bounds": {
    "nw": {
      "lat": 1,
      "lng": 1
    },
    "se": {
      "lat": 1,
      "lng": 1
    }
  },
  "lang": "text",
  "with_details": true
}
{
  "success": true,
  "locations": [
    {
      "lat": 1,
      "lng": 1,
      "address": "text",
      "details": {
        "country": "text",
        "province": "text",
        "locality": "text",
        "street": "text",
        "house": "text",
        "postcode": "text",
        "bounds": {
          "nw": {
            "lat": 1,
            "lng": 1
          },
          "se": {
            "lat": 1,
            "lng": 1
          }
        }
      }
    }
  ]
}

Errors

These errors come in addition to the general error codes:

  • 210 - No location matched the query.

Search location

post
/geocoder/search_location

Reverse geocoding: return the address at a coordinate pair.

The point may be given either as the location object or as separate top-level lat and lng parameters. location wins if both are present.

Authorizations
AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body
latnumberOptional

Latitude. Use with lng instead of location.

lngnumberOptional

Longitude. Use with lat instead of location.

geocoderstring · enumOptional

Optional. Preferred geocoder. Accounts with premium GIS always use Google regardless of this value.

Possible values:
langstring · max: 5Optional

Optional. ISO 639 language code for the result, at most 5 characters, for example en or en_US. Defaults to the session language.

with_detailsbooleanOptional

Optional. Default false. Include the parsed details object in the response.

goalstring · enumOptional

Optional. Default ui. What the lookup is for, which decides the geocoder chosen. Use ui_user_action for a lookup a user asked for directly, ui otherwise. An unrecognised value is silently treated as ui.

Possible values:
Responses
200

The address

application/json
successbooleanRead-onlyOptional

true if request finished successfully.

Example: true
valuestringOptional

The address at the point.

post/geocoder/search_location
POST /v2/geocoder/search_location HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "location": {
    "lat": 1,
    "lng": 1
  },
  "lat": 1,
  "lng": 1,
  "geocoder": "google",
  "lang": "text",
  "with_details": true,
  "goal": "ui"
}
{
  "success": true,
  "value": "text",
  "details": {
    "country": "text",
    "province": "text",
    "locality": "text",
    "street": "text",
    "house": "text",
    "postcode": "text",
    "bounds": {
      "nw": {
        "lat": 1,
        "lng": 1
      },
      "se": {
        "lat": 1,
        "lng": 1
      }
    }
  }
}
PreviousDelivery info
NextMap layer

Last updated

Was this helpful?