ForHosting KIT · Voyages et géographie

Face du cube S2 depuis lat/lon : quelle face contient le point

Trouvez sur laquelle des six faces du cube S2 tombe un point : San Francisco, en (37,7749 ; -122,4194), se trouve sur la face 4, la face -Y, en u -0,918061185048 et v -0,635094359374. C'est la première étape avant de construire des cellules S2. Gratuit dans votre navigateur.

Gratuit
Fonctionne dans votre navigateur
Sans inscription
Vos données restent sur votre appareil

Lancer gratuitement Voir l’API

Utilisez-le depuis WebAPIE-mailTelegramApp bientôt

Exemple résolu

Si vous saisissez

Latitude: 37,7749
Longitude: -122,4194

Vous obtenez

Face: 4
Nom de la face: -Y
X: -0,4237560025
Y: -0,6672331383

La bibliothèque de géométrie S2 de Google découpe la Terre en projetant la sphère unité sur un cube, puis en subdivisant récursivement chaque face en une hiérarchie de cellules. Cette capacité accepte lat et lon WGS84, les convertit en un vecteur de direction unitaire et renvoie l'indice de face S2 (de 0 à 5), un nom lisible tel que +X ou -Z, les composantes cartésiennes unitaires et les coordonnées UV du point sur cette face dans l'intervalle conventionnel de moins un à plus un. Utilisez-la pour construire des index spatiaux, enseigner la géométrie sphérique ou vérifier que vos propres liaisons S2 choisissent la même face que la bibliothèque de référence aux cas limites près des frontières de faces.

Comment lat/lon devient une face du cube S2

Les six faces du cube S2 correspondent aux six demi-espaces définis par l'axe cartésien dominant : la face zéro est la face plus X, la une plus Y, la deux plus Z, la trois moins X, la quatre moins Y et la cinq moins Z.

L'implémentation suit la même règle de plus grande composante absolue que la bibliothèque S2 de Google : comparez les valeurs absolues de x, y et z ; l'axe de plus grande magnitude décide de la paire de faces ; le signe de cette composante décide laquelle des deux faces opposées est retenue. En cas d'égalité exacte, l'indice d'axe le plus élevé l'emporte, comme LargestAbsComponent de S2, afin que les points sur les coutures entre faces se résolvent de façon déterministe.

Une fois la face connue, les coordonnées UV sur cette face s'obtiennent en divisant les deux composantes non dominantes par la dominante avec les changements de signe spécifiques à chaque face publiés dans ValidFaceXYZToUV de S2, produisant des valeurs dans l'intervalle fermé de moins un à plus un qui situent le point dans la face carrée avant toute hiérarchie de cellules supplémentaire.

Où la recherche de face S2 apporte de la valeur

Les générateurs pédagogiques et d'examens qui enseignent les grilles globales discrètes peuvent demander aux élèves la face d'une ville et noter contre un oracle déterministe plutôt que des cahiers d'enseignants instables. Les pipelines d'analytique de journaux qui regroupent des échantillons GPS par face S2 pour un routage grossier ou des découpages géographiques A/B appellent une fois par événement et stockent l'entier de face à côté des coordonnées brutes. Une validation échouée ne consomme pas le solde.

Gardez les requêtes compactes, figez l'entier de face et l'UV arrondi dans les tests, et vous obtenez une affectation de face reproductible pour index, leçons et workers de bord sans monter une pile complète de géométrie sphérique.

Cas d’usage

Prélude à l'encodage de cellules S2

Déterminez laquelle des six faces du cube contient un lat/lon avant de calculer des identifiants de cellules S2 hiérarchiques ou des couvertures de région dans un worker qui ne peut pas charger la bibliothèque S2 complète.

Enseignement des grilles globales discrètes

Laissez les élèves soumettre des coordonnées de villes et vérifier l'indice de face contre un oracle qui suit la règle de plus grande composante absolue de Google, y compris les pôles et les coutures entre faces.

Regroupement géographique grossier

Regroupez des événements GPS par face S2 pour des tableaux de bord de routage ou des découpages géographiques A/B sans calculer d'identifiants de cellules complets pour chaque échantillon.

Questions fréquentes

Que signifient les faces de 0 à 5 ?

Elles suivent la convention S2 de Google : 0=+X, 1=+Y, 2=+Z (nord), 3=-X, 4=-Y, 5=-Z (sud). Le choix est la plus grande composante cartésienne absolue du vecteur unitaire.

Que sont u et v dans la réponse ?

Les coordonnées UV situent le point sur la face du cube choisie dans l'intervalle [-1, 1], avec les mêmes conventions de signe ValidFaceXYZToUV que S2.

Comment trouve-t-on la face du cube S2 d'un point ?

La latitude et la longitude deviennent un vecteur unitaire à trois composantes. La composante la plus grande en valeur absolue choisit l'axe, et son signe décide laquelle des deux faces opposées reçoit le point.

Quelle face reçoit un point situé pile sur l'arête entre deux faces ?

L'égalité est toujours tranchée de la même façon : si deux composantes du vecteur unitaire sont aussi grandes l'une que l'autre, l'axe d'indice le plus élevé l'emporte. Un point situé sur une limite ne saute donc jamais d'une face à l'autre.

Cet outil donne-t-il l'identifiant complet de la cellule S2 ?

Non. Il identifie seulement la face, le vecteur unitaire et la position u et v sur cette face. Pour l'identifiant complet, utilisez ces valeurs avec un encodeur de cellules S2.

Outils associés

Pour les développeurs — accès API

Tout sur cette page est disponible par programmation. Cette section s'adresse aux équipes qui veulent l'intégrer à leurs systèmes ; les autres peuvent simplement utiliser l'outil ci-dessus.

Endpoint

POSThttps://api.kit.forhosting.com/geo/s2-face-from-latlon

Authentification par jeton Bearer : un seul POST met la tâche en file d’attente, et le résultat vous parvient par webhook ou lien signé.

Appeler depuis votre stack

curl -X POST https://api.kit.forhosting.com/geo/s2-face-from-latlon \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":37.7749,"lon":-122.4194}'

const res = await fetch("https://api.kit.forhosting.com/geo/s2-face-from-latlon", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "lat": 37.7749,
    "lon": -122.4194
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/geo/s2-face-from-latlon",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "lat": 37.7749,
    "lon": -122.4194
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/geo/s2-face-from-latlon", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"lat":37.7749,"lon":-122.4194}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"lat":37.7749,"lon":-122.4194}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/geo/s2-face-from-latlon", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Exemple de requête

{
  "lat": 37.7749,
  "lon": -122.4194
}

Exemple de réponse

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "geo.s2_face_from_latlon",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

L’API est asynchrone : chaque appel renvoie un task_id immédiatement, puis vous interrogez l’état à raison d’une requête par seconde.

Tarifs

par requête$0.002

Le prix est publié, sans tokens ni crédits. Une tâche qui échoue n’est pas facturée.

Erreurs

HTTP	Code	Signification
`401`	`unauthorized`	Clé API absente ou invalide : vérifiez l’en-tête Authorization.
`402`	`insufficient_balance`	Solde insuffisant : rechargez votre compte pour lancer cette tâche.
`404`	`unknown_type`	Type de tâche inconnu : vérifiez le champ type de votre requête.
`429`	`rate_limited`	Trop de requêtes : ralentissez la cadence, puis réessayez.

Notes techniques

Avant d'encoder un identifiant de cellule S2, de calculer une couverture ou de raisonner sur l'intersection de régions, il faut savoir laquelle des six faces de ce cube contient une latitude et une longitude données. L'algorithme est purement analytique, sans appels réseau ni état aléatoire, de sorte que le parcours gratuit du navigateur et le parcours API payant coïncident toujours.

Comment lat/lon devient une face du cube S2

Partez d'une latitude et d'une longitude en degrés décimaux sur la sphère WGS84. Convertissez la latitude en angle polaire depuis l'équateur et la longitude en azimut depuis le méridien de Greenwich, tous deux en radians. Le vecteur de direction unitaire vaut alors x égal à cos(latitude) cos(longitude), y égal à cos(latitude) sin(longitude) et z égal à sin(latitude), avec z positif vers le pôle nord et x positif vers latitude zéro, longitude zéro.

Contrat d'entrée, champs de réponse et erreurs de validation

Associez cette réponse à votre propre encodeur de cellules S2 si vous avez besoin d'identifiants de cellules complets ; ce point de terminaison n'identifie que la face et la position UV sur celle-ci. Envoyez en POST un corps JSON avec deux nombres finis obligatoires : lat (ou l'alias latitude) entre moins quatre-vingt-dix et quatre-vingt-dix inclus, et lon (ou les alias lng et longitude) entre moins cent quatre-vingts et cent quatre-vingts inclus. Les chaînes numériques sont acceptées comme des nombres JSON. Champs manquants, chaînes vides, valeurs non finies telles que NaN ou Infinity, et latitudes ou longitudes hors plage échouent avec invalid_input et ne sont pas facturés. En cas de succès, la réponse renvoie lat et lon nettoyés, l'entier face de zéro à cinq, face_name parmi +X, +Y, +Z, -X, -Y ou -Z, les composantes du vecteur unitaire x, y et z, la paire UV locale de face u et v, et method égal à s2_face_from_unit_sphere pour que les clients documentent la projection utilisée. Exemple : San Francisco près de la latitude 37.7749 et de la longitude négative 122.4194 tombe sur la face quatre (moins Y) car la plus grande composante absolue du vecteur unitaire est un y négatif. Le pôle nord (latitude 90, longitude 0) tombe sur la face deux (plus Z). La longitude zéro équatoriale (latitude 0, longitude 0) tombe sur la face zéro (plus X).

Où la recherche de face S2 apporte de la valeur

Les plateformes cartographiques et SIG qui exposent des identifiants de cellules S2 pour le recouvrement de régions ont besoin d'une première vérification de face alignée sur la bibliothèque de production ; une petite API parse évite d'embarquer une liaison C++ ou Java complète dans chaque worker de bord uniquement pour savoir sur quelle face du cube se pose une épingle. Comme l'implémentation est pure parse de niveau A, chaque appel réussi coûte le prix de base publié $0.002 sans jetons de modèle ni réseau sortant.

Questions techniques

Comment trouver la face du cube S2 d'une latitude et d'une longitude ?

Envoyez lat finie dans [-90, 90] et lon dans [-180, 180]. L'API renvoie face 0–5, face_name (+X…-Z), le vecteur unitaire x/y/z et l'UV sur cette face.

Que se passe-t-il si la latitude ou la longitude est hors plage ?

La tâche échoue avec invalid_input. La latitude doit être dans [-90, 90] et la longitude dans [-180, 180] ; les requêtes invalides ne sont pas facturées.

Combien coûte l'outil de face du cube S2 depuis lat/lon ?

L'outil navigateur est gratuit. Les requêtes API utilisent le solde prépayé KIT à $0.002 par appel réussi ; une entrée invalide n'est pas facturée.

Consulter la documentation complète du KIT →

Lancer gratuitement

Exemple résolu

Comment lat/lon devient une face du cube S2

Où la recherche de face S2 apporte de la valeur

Cas d’usage

Prélude à l'encodage de cellules S2

Enseignement des grilles globales discrètes

Regroupement géographique grossier

Questions fréquentes

Outils associés

Pour les développeurs — accès API

Endpoint

Appeler depuis votre stack

Exemple de requête

Exemple de réponse

Tarifs

Erreurs

Notes techniques

Comment lat/lon devient une face du cube S2

Contrat d'entrée, champs de réponse et erreurs de validation

Où la recherche de face S2 apporte de la valeur

Questions techniques

merci