Requête POST vers le service Geocode

La requête POST vous permet d'envoyer une seule adresse d'entrée ou une liste d'adresses pour le traitement par lots. Il est possible d'indiquer, en option, des préférences de correspondance et/ou de géocodage pour le service Geocode et de recevoir les coordonnées de latitude/longitude associées et des informations de localisation. 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/geocode.[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 :

addresses - L'adresse ou les adresses à géocoder. Obligatoire.
type - Le type de géocode. Facultatif.
preferences - Les options de correspondance et de géocodage. Facultatif.

Ces objets et leurs éléments sont définis dans le tableau suivant.

Paramètre	Type	Description
Remarque : La signification, les valeurs valides et la prise en charge des éléments d'adresse suivants varient selon le pays : placeName mainAddress lastLine areaName1 areaName2 areaName3 areaName4 postCode1 postCode2 country En outre, il existe certaines options de correspondance et de géocodage qui varient selon le pays. Il est important de vérifier les informations spécifiques à votre/vos pays. Pour trouver les informations de votre pays, reportez-vous aux sections informations spécifiques au pays de l'annexe.
Tableau addresses d'objets Address. La série d'adresses peut contenir une ou plusieurs adresses d'entrée. Chaque objet Address peut contenir les éléments suivants :
placeName	Chaîne	Nom de bâtiment, nom de lieu, point d'intérêt (POI), nom d'entreprise ou de société associés à l'adresse d'entrée. Facultatif. Par exemple : Pitney Bowes 4750 Walnut St. Boulder, CO 80301
mainAddress	Chaîne	Entrée sur une seule ligne : si aucun autre champ n'est renseigné, l'entrée mainAddress est traitée comme une entrée sur une seule ligne et peut être une collection d'éléments de champs d'adresse. L'ordre d'entrée des champs d'adresse doit refléter la mise en forme d'adresse normale de votre pays. Facultatif. Par exemple : 4750 Walnut St., Boulder CO, 80301 Adresse de rue : si les champs d'adresse (placeName, lastLine, postalCode, etc.) sont fournis séparément, le contenu de ce champ est traité comme la partie de l'adresse de rue et peut inclure le nom de société, le numéro de résidence, les noms de bâtiment et les noms de rue. Facultatif. Entrée d'intersection de rues : pour saisir une intersection, spécifiez les deux noms de rue séparés par une double esperluette (&&).
lastLine	Chaîne	Dernière ligne de l'adresse. Facultatif.
areaName1	Chaîne	Spécifie la plus grande zone géographique, en général, un état ou une province. Facultatif.
areaName2	Chaîne	Spécifie la zone géographique secondaire, généralement un comté ou un district. Facultatif.
areaName3	Chaîne	Indique un nom de ville ou d'agglomération. Facultatif.
areaName4	Chaîne	Indique une localité ou une sous-division de ville. Facultatif.
postCode1	Chaîne	Le code postal au format approprié pour le pays. Facultatif.
postCode2	Chaîne	Extension de code postal au format approprié au pays. Facultatif.
country	Chaîne	Code pays ISO 3166-1 alpha-3. Obligatoire. Pour connaître les codes pays, reportez-vous à la section Liste de référence de pays et codes de pays ISO 3166-1.
addressNumber	Chaîne	Numéro de résidence ou de bâtiment.
streetName	Chaîne	Nom de rue.
unitType	Chaîne	Spécifie le type d'unité, comme Apt., Ste. et Bât.
unitValue	Chaîne	Spécifie la valeur/le numéro d'unité, comme « 3B ».
Objet type de typegeocodeType :
geocodeType	Chaîne	Indique le type de géocode à effectuer. Facultatif. Address Géocode d'une adresse de rue. Par défaut. Geographic Géocode au niveau du centroïde géographique d'une ville ou d'un état. Postal Géocode au niveau d'un code postal.
Objet preferences de type Preferences, constitué des éléments suivants. Remarque : Les éléments suivants ne sont applicables qu'au service 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 de 3 caractères et d'un point. Par exemple, `DEU.fallbackToGeographic`.
returnAllCandidateInfo	Booléen	Spécifie s'il faut renvoyer toutes les informations disponibles pour chaque candidat. True Renvoie toutes les informations disponibles pour chaque candidat. False Ne renvoie pas toutes les informations disponibles pour chaque candidat. Par défaut.
fallbackToGeographic	Booléen	Spécifie sil faut ou non tenter de déterminer un centroïde de région géographique lorsqu'un niveau d'adresse de géocode ne peut être déterminé. Facultatif. True Renvoie un centroïde géographique lorsqu'un centroïde au niveau de l'adresse ne peut pas être déterminé. Par défaut. False Ne renvoie pas de centroïde géographique lorsqu'un niveau d'adresse de centroïde ne peut pas être déterminé.
fallbackToPostal	Booléen	Spécifie s'il faut ou non tenter de déterminer un centroïde de code postal lorsqu'un géocode au niveau de l'adresse ne peut pas être déterminé. Facultatif. True Renvoie un centroïde de code postal lorsqu'un centroïde de niveau d'adresse ne peut pas être déterminé. Par défaut. False Ne renvoie pas de centroïde de code postal lorsqu'un centroïde de niveau d'adresse ne peut pas être déterminé.
FALLBACK_TO_WORLD	Chaîne	Indique s'il faut utiliser World Geocoder (XWG) pour définir un géocode lorsqu'aucun géocodeur pays n'est installé ou lorsqu'un géocodeur pays est installé sans jeu de données de géocodage. World Geocoder (XWG) peut renvoyer un géocode postal ou géographique suivant le niveau de prise en charge du jeu de données de géocodage XWG. Facultatif. True Utiliser World Geocoder (XWG) pour la correspondance lorsqu'aucun géocodeur pays n'est installé ou lorsqu'un géocodeur pays est installé sans jeu de données de géocodage. False Ne pas utiliser World Geocoder (XWG) pour la correspondance lorsqu'aucun géocodeur pays n'est installé ou lorsqu'un géocodeur pays est installé sans jeu de données de géocodage. Par défaut.
maxReturnedCandidates	Entier	Nombre maximal de candidats à renvoyer. Facultatif. Il doit s'agir d'une valeur entière. Valeur par défaut = 1.
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
matchMode	Chaîne	Les modes de correspondance déterminent la tolérance utilisée pour effectuer une correspondance entre l'adresse d'entrée et les données de référence. Sélectionnez un mode de correspondance en fonction de la qualité de votre entrée et de la sortie de votre choix. Les modes de correspondance suivants sont disponibles : Exact Requiert une correspondance très serrée. Ce mode restrictif génère le plus petit nombre de candidats de correspondance, ce qui réduit le temps de traitement. Si vous utilisez ce mode, assurez-vous que votre entrée est très propre, sans aucune faute d'orthographe ni adresse incomplète. Standard Requiert une correspond proche et génère un nombre modéré de correspondances de candidats. Par défaut. Relaxed Permet une correspondance approximative et génère le plus grand nombre de candidats, ce qui augmente la durée de traitement et entraîne plus de correspondances multiples. Utilisez ce mode si vous n'êtes pas sûr que votre entrée soit propre, sans aucune faute d'orthographe ni adresse incomplète. Custom Vous permet de définir des critères de correspondance en configurant les champs MustMatch ; cependant, vous pouvez configurer les champs MustMatch uniquement à l'aide d'une requête POST . Pour utiliser une requête GET, vous devez conserver les valeurs par défaut de MustMatch. Pour plus d'informations sur les champs MustMatch, reportez-vous à la section mustMatchFields. Interactive (USA only) Disponible dans la correspondance d'adresse sur une seule ligne uniquement. Ce mode est conçu pour mieux gérer les défis de correspondance spécifiques de la mise en correspondance interactive. Le mode interactif permet des modèles de correspondance plus flexibles et peut, dans certains cas, renvoyer des correspondances possibles supplémentaires en plus de celles renvoyées par le mode de correspondance approximative. CASS (USA only) Impose des règles supplémentaires pour garantir le respect des réglementations USPS CASS. L'objectif de ce mode de correspondance est de créer des adresses aptes à recevoir du courrier pour les remises tarifaires USPS. Utilisez ce mode pour normaliser votre entrée de publipostage. Ce mode donne un grand nombre de candidats.
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`.
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, mustMatchFields 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 à 3 caractères ISO-3166 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>USA.maxReturnedCandidates</key> <value>3</value> </entry> </customPreferences>` Les options d'entrée de pays personnalisées sont disponibles pour les pays suivants : Australie (AUS) Canada (CAN) France (FRA) Allemagne (DEU) Grande-Bretagne (GBR) Nouvelle-Zélande (NZL) Portugal (PRT) Singapour (SGP) Suède (SWE) États-Unis (USA) 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.
preferredDictionaryOrder	List<String>	Indique l'ordre de recherche des dictionnaires lorsque plusieurs dictionnaires sont installés. L'ordre de recherche par défaut est l'ordre dans lequel les dictionnaires sont configurés.
Objet mustMatchFields de type FieldsMatching. Permet de définir les critères de correspondance pour déterminer les candidats correspondants. Pour activer ces options, vous devez définir le champ matchMode sur `Custom`. Cet objet comprend les éléments suivants : Remarque : Pour remplacer la valeur par défaut d'un élément mustMatchFields 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, `CAN.matchOnAddressNumber`.
matchOnAddressNumber	Booléen	True Une correspondance doit être effectuée au niveau du numéro d'adresse d'entrée. False Une correspondance n'est pas nécessaire au niveau du numéro d'adresse d'entrée. Par défaut.
matchOnPostCode1	Booléen	True Une correspondance doit être effectuée au niveau du champ d'entrée PostCode1. False Une correspondance n'est pas nécessaire au niveau du champ d'entrée PostCode1. Par défaut.
matchOnAreaName1	Booléen	True Une correspondance doit être effectuée au niveau du champ d'entrée AreaName1. False Une correspondance n'est pas nécessaire au niveau du champ d'entrée AreaName1. Par défaut.
matchOnAreaName2	Booléen	True Une correspondance doit être effectuée au niveau du champ d'entrée AreaName2. False Une correspondance n'est pas nécessaire au niveau du champ d'entrée AreaName2. Par défaut. Remarque : Cette option n'est pas prise en charge par les États-Unis.
matchOnAreaName3	Booléen	True Une correspondance doit être effectuée au niveau du champ d'entrée AreaName3. False Une correspondance n'est pas nécessaire au niveau du champ d'entrée AreaName3. Par défaut.
matchOnAreaName4	Booléen	True Une correspondance doit être effectuée au niveau du champ d'entrée AreaName4. False Une correspondance n'est pas nécessaire au niveau du champ d'entrée AreaName4. Par défaut.
matchOnAllStreetFields	Booléen	True Une correspondance doit être effectuée au niveau des champs de nom de rue, de type et de points cardinaux d'entrée. False Une correspondance n'est nécessaire au niveau des champs de nom de rue, de type et de points cardinaux d'entrée. Par défaut.
mustMatchInput	Booléen	True Les autres champs de correspondance obligatoire sont ignorés et tous les champs d'entrée potentiels fournis (code postal, nom de région, etc.) doivent correspondre aux candidats pour le candidat renvoyé. False Les autres champs de correspondance obligatoire sont honorés. Il n'est pas nécessaire qu'une correspondance soit faite avec un champ d'entrée particulier pour le candidat à renvoyer. Par défaut.
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.