Requête POST Reverse Geocode

La requête POST vous permet d'envoyer une seule coordonnée d'entrée ou une liste de coordonnées pour le traitement par lots. Il est également possible, en option, d'indiquer un code pays, un système de coordonnées de référence et des préférences de correspondance. Une réponse contenant une liste de candidats avec leurs données d'adresse associées et des informations de correspondance est renvoyée. Les options de préférence d'une requête POST constituent l'ensemble complet d'options disponibles.

Base URI

http://<server>:<port>/rest/GlobalGeocode/reverseGeocode.[content type]

où :

.[content type] indique que le type de contenu spécifié est utilisé par défaut. Facultatif.
json
Le type de contenu par défaut est JSON, sauf s'il est remplacé par une négociation de contenu HTTP.
xml
Le type de contenu par défaut est XML, sauf s'il est remplacé par une négociation de contenu HTTP.

Paramètres de requête

La requête POST comprend les paramètres d'entrée suivants :
  • points — Les coordonnées d'entrée ou plusieurs coordonnées d'entrée à géocoder en sens inverse. Obligatoire.
  • preferences — Les options de correspondance. Facultatif.
Ces objets et leurs éléments sont définis dans le tableau suivant.
Nom Type Description
points Objet de tableau contenant un objet de géométrie et une chaîne de code de pays :
country Chaîne Indique le pays dans lequel rechercher le résultat de géocode inverse, spécifié à l'aide d'un code pays ISO de 3 lettres. Facultatif. Pour connaître les codes pays, reportez-vous à la section Liste de référence de pays et codes de pays ISO 3166-1.
Objet geometry, composé des éléments suivants :
coordinates Double Spécifie les coordonnées d'entrée x, y, où x = longitude et y = latitude. Par exemple : [ -105.25175, 40.024494 ]
type Chaîne Indique le type d'entité géographique représenté par les coordonnées d'entrée.
point
Les coordonnées d'entrée représentent un emplacement de point.
crs Chaîne Indique le système de référence de coordonnées utilisé pour les coordonnées d'entrée. Le format doit respecter le code European Petroleum Survey Group (EPSG) ou le code SRID. Valeur par défaut = EPSG:4326. Désignez le système de référence de coordonnées au format codespace:code.
Objet preferences, composé des éléments suivants :
Remarque : Seuls les éléments suivants de l'objet preferences sont applicables au service Reverse Geocode.
Remarque : Pour remplacer la valeur par défaut d'un élément preferences pour un pays en particulier, indiquez la paire clé/valeur dans l'objet customPreferences, avec la constante de clé précédée du code pays ISO-3166 à 3 caractères et d'un point. Par exemple, DEU.streetOffset.
distance Double Définit le rayon dans lequel Reverse Geocode Service recherche une correspondance aux coordonnées d'entrée. L'unité de mesure est précisée via distanceUnits. Valeur par défaut = 150 mètres. Valeur maximale = 5 280 pieds(1 mile) ou 1 609 mètres.
distanceUnits Chaîne Indique l'unité de mesure de la distance de recherche. L'un des éléments suivants :
  • Feet
  • Meters - Default
clientLocale Chaîne Ce champ est utilisé pour un pays qui dispose de plusieurs langues pour déterminer l'ordre de préférence des candidats de langue. Les paramètres régionaux doivent être spécifiés au format « cc_CC », où « cc » est la langue et « CC » le code ISO 3166-1 Alpha-2, comme : en_US, fr_CA ou fr_FR.

Par exemple, l'Égypte prend en charge l'anglais et arabe. Le champ clientLocale peut être défini soit sur anglais en premier (en-EN), soit sur arabe en premier (ar-EG).

Remarque : Pour obtenir une liste des codes ISO Alpha-2, reportez-vous à la section Liste de référence de pays et codes de pays ISO 3166-1.
clientCoordSysName Chaîne Spécifie le système de coordonnées que vous souhaitez convertir en géométrie. Le format doit respecter le code European Petroleum Survey Group (EPSG) ou le code SRID. Valeur par défaut = EPSG:4326.

Spécifie le système de référence de coordonnées au format codespace:code.
streetOffset Double Indique la distance de décalage par rapport au segment de rue à utiliser dans le géocodage de niveau d'adresse. La distance est indiquée dans les unités spécifiées dans l'option streetOffsetUnits. Valeur par défaut = 7 mètres.

La distance de décalage est utilisée dans le géocodage de niveau de rue pour éviter le géocodage au milieu d'une rue. Il compense le fait que le géocodage de niveau de rue renvoie un point de latitude et longitude au centre de la rue où se trouve l'adresse. Puisque le bâtiment représenté par une adresse n'est pas dans la rue elle-même, vous ne voulez pas le géocode d'un point dans la rue. Au lieu de cela, vous souhaitez le géocode pour représenter l'emplacement de l'immeuble situé à côté de la rue. Par exemple, un décalage de 50 pieds signifie que le géocode représentera un point de 50 pieds en arrière depuis le centre de la rue. La distance calculée est perpendiculaire à la partie du segment de la rue pour l'adresse. Le décalage est également utilisé pour éviter que les adresses situées l'une en face de l'autre dans la rue n'aient le même point. Le schéma suivant représente un point de décalage par rapport au point d'origine.
streetOffsetUnits Chaîne Spécifie l'unité de mesure de décalage d'une rue. L'un des éléments suivants :
  • Feet
  • Meters - Default
cornerOffset Double Spécifie la distance pour décaler les extrémités dans la correspondance de niveau de rue. La distance est indiquée dans les unités spécifiées dans l'option cornerOffsetUnits. Cette valeur est utilisée pour éviter que les adresses aux angles de rue ne reçoivent le même géocode que celui de l'intersection. Définit la position de décalage du point géocodé par rapport à l'angle. Valeur par défaut = 7 mètres.

Le schéma suivant compare les points d'extrémité d'une rue aux points de décalage.
cornerOffsetUnits Chaîne Spécifie l'unité de mesure du décalage d'une rue. L'un des éléments suivants :
  • Feet
  • Meters - Default
customPreferences Map<String key, String value> Indique les préférences d'entrée spécifiques au pays. Cet objet peut être utilisé pour indiquer :
  • Un remplacement de pays par une valeur par défaut d'un ou de plusieurs éléments des objets preferences ou returnFieldsDescriptor.
  • Une option d'entrée de pays personnalisée.
Pour remplacer la valeur par défaut pour un pays en particulier, faites précéder la clé constante du code de pays ISO-3 et d'un point, puis précisez la valeur. Par exemple, dans une requête XML, une entrée pour un remplacement de pays ressemblerait à ceci :
<customPreferences>
   <entry>
      <key>CAN.distance</key>
      <value>300</value>
   </entry>
</customPreferences>
Les options d'entrée de pays personnalisées sont disponibles pour les pays suivants : En outre, pour les pays qui prennent en charge les dictionnaires utilisateur personnalisés et les jeux de données de géocodage standard, vous pouvez définir une préférence personnalisée avec la clé KEY_CUSTOM_DICTIONARY_USAGE, qui définit les préférences de recherche et de correspondance lorsque des dictionnaires standard et personnalisés sont disponibles dans le moteur de géocodage. Cette option est uniquement disponible avec le géocodage avant. Pour plus d'informations, reportez-vous à la section Définition des préférences de recherche et de correspondance lors de l'utilisation de dictionnaires standard ou personnalisés. Pour localiser des informations si votre pays prend en charge les dictionnaires utilisateur personnalisés, reportez-vous à la section « Jeux de données de géocodage pris en charge » du pays.
Objet returnFieldsDescriptor de type ReturnsFieldsDescriptor. Contrôle le renvoi de données supplémentaires sur un candidat. Par défaut, les informations de candidat étendues ne sont pas renvoyées, mais, dans les cas où des informations supplémentaires sont disponibles, cette fonction peut être contrôlée comme suit :
Remarque : Pour remplacer la valeur par défaut d'un élément returnFieldsDescriptor pour un pays en particulier, indiquez la paire clé/valeur dans l'objet customPreferences, avec la constante de clé précédée du code pays ISO-3166 de 3 caractères et d'un point. Par exemple, AUS.returnAllCustomFields.
returnAllCustomFields Booléen
True
Renvoie tous les champs personnalisés pour le candidat.
False
Renvoie uniquement l'ensemble standard de champs pour le candidat. Par défaut.
returnedCustomFieldKeys List<String> Spécifie une liste de clés qui représentent les champs personnalisés à renvoyer dans la sortie customFields du candidat. Par exemple, « CTYST_KEY » ou « DATATYPE ». Par défaut : vierge
Remarque : Pour indiquer différents paires de clé/valeur pour un pays, utilisez des espaces pour séparer les noms des champs personnalisés à renvoyer. Par exemple : "USA.returnedCustomFieldKeys" : "LAT LON SHORT_CITY". Les candidats possédant ces informations disponibles incluent les trois champs personnalisés avec ces clés dans la sortie customFields du candidat.
Remarque : Les champs personnalisés varient selon le pays. Pour rechercher les informations de votre pays, reportez-vous à la section Informations spécifiques aux pays pour trouver la section correspondante de l'annexe qui fournit davantage de détails.
returnMatchDescriptor Booléen
True
Renvoie l'objet Descripteur de correspondance, qui indique les parties du candidat correspondant à l'adresse d'entrée.
False
Ne renvoie pas d'objet Descripteur de correspondance. Par défaut.
returnStreetAddressFields Booléen
True
Renvoie tous les champs de rue individuels qui composent séparément le champ formattedStreetAddress, comme suit :
  • MAIN_ADDRESS — partie de base du nom de rue. Par exemple : « River » dans « 13 River Ave ».
  • THOROUGHFARE_TYPE — Type de voie publique, qui peut apparaître avant ou après le nom de rue, comme Ave, Via, St, Rd, etc.
  • ADDRESS_ID — Identificateur unique de l'adresse dans les données sources.
  • PRE_ADDRESS — Valeur pouvant contenir des articles, etc., qui apparaissent avant le nom de rue principal. Par exemple: « de la » dans « Calle de la mesa ».
  • POST_ADDRESS — Valeur pouvant contenir des expressions qui apparaissent après le nom de rue principal. Par exemple : « de la tiedra » dans « Ramon Perez de la tiedra ».
  • PRE_DIRECTIONAL — Valeur pouvant contenir un cardinal qui apparaît avant le nom de rue principal. Par exemple : « South » dans « 123 South Main St ».
  • POST_DIRECTIONAL — Valeur pouvant contenir un cardinal qui apparaît après le nom de rue principal. Par exemple : « SW » dans « 123 River St SW ».
False
Ne renvoie pas séparément les champs de rue individuels ; renvoie ces valeurs dans le champ formattedStreetAddress. Par défaut.
returnUnitInformation Booléen
True
Si disponible, renvoie les informations de type d'unité et de valeur d'unité séparément dans les champs unitType et unitValue, ainsi que dans le champ formattedStreetAddress.
False
Si disponible, renvoie les informations de type d'unité et de valeur d'unité uniquement dans le champ formattedStreetAddress. Par défaut.