geocoders / geocodejson-spec Goto Github PK

If it is supported anywhere - maybe add readme listing implementations following it?

Introducing properties like "name", "label", "accuracy" into feature properties simply won't work; collisions with other applications are certain. To avoid collisions, I recommend creating a namespace for properties specific to this application – geocoding, maybe – and define properties like feature['properties']['geocoding']['name']. A collection['version'] property won't work for the same reason, and so I also recommend a geocoding namespace for the feature collection object.

This approach is being used at https://github.com/mapbox/geojson-coordinate-properties.

👋 Hello. I'd like to contribute to creating a standard for geocoding responses. Some of my tasks will be to put the schema in a JSON-Schema format (https://json-schema.org/) and also create a web app that can validate results checking conformance with the schema as well as suggesting improvements and plugins to the existing schema.

What is the best way for me to help? Should I contribute Pull Requests to this repository or should I create my own repo? Thank you and have a great day :-)

Every geocoder API use postalcode in place of postcode.

"city", "district", "county", "state", "country"
This list of fields have the same meaning as admin one, haven't ?

Hi,

According to the spec:

  // OPTIONAL. Name of the place.
      "name": "My Shoes Shop",

For street addresses, the Addok geocoder returns street number + street name as the name.
I would expect the name to designate only place names when they have one.

What is the semantic of this property?
Is it synthetic?

There is an issue, when you looking for big admin. boundary or a way, encoding a full geometry into the answer may cause a big overhead, but this is a required field.

So in many cases, we want to return centroids (or any kind of reference points only). For such purposes, there is centroid field in GeoJSON geomery object. But I think it couldn't be used without coordinates of geometry.

So do someone see the way how not to return centroids instead of full geometries and not to break GeoJSON compatibility?

We need a way to return a meta data about geocoder, such as:

Capabilities

For instance, do geocoder have:

• Inverse geocoding API
• search as you type API
• fuzzy searching
• massive geocoding API
• POIs search (it may be a part of regular search api, standalone endpoint )
• Indexing API (is it possible to fetch sitemap.xml and html snapshots of addresses)

"capabilities": {
     "inverse_geocode": {
          // Required
          "endpoint": "mygeocoder.org/inverse/meta"
     },
     "live_search": {
          "endpoint": "mygeocoder.org/live/meta",
          // Minimal length of query, optional.   
          "minimal_length": 2
     }
}

Languages

For instnce, my geocoder have been optimized for russian language. It may be used for any other language, but with ru queries it gains some advantages.

Maybe something like preffered locale in http will fit our needs.

Coverage

For which territories our geocoder is suitable

"coverage": [{ 
        "name":"Russia",
        "internal_id":"12345",
        "country":"ru",
        "geometry": {
              "type": "polygon",
              "last_update": "timestamp",
              "coordinates": [....]
        }
    }, {
       //some other territory    
    }
]

In the spec:

      // OPTIONAL. County of the place.
      "county": null,

      // OPTIONAL. State of the place.
      "state": null,

      // OPTIONAL. Country of the place.
      "country": "France",

Is county a typo for country? But then there's country just after... ??

No fundamental changes in draft spec.

• rename draft folder to v1
• update revision from 0.1 to 1.0
• fix copyright notice (CC0 is public domain, not attribution)
• remove all default: null (optional attributes can be simply omitted)
• add examples for all attributes (ie. no "district": null)
• remove all TODO notices
• refactor spec text taking inspiration from RFC7946 (GeoJSON spec)
• build an index.html file from spec md file (served as homepage, ie. using markdown-to-html-cli)
• add JSON Schema with checksum #24
• build an interactive page to navigate spec schema (ie. using @stoplight/json-schema-viewer)
• enable github pages to serve static content
• add a changelog
• add a code of conduct
• add contributing guidelines
• add a LICENSE file
• enrich README in root folder
• define issue templates: proposal, bug, q&a, use case report
• close all open issues

There is a case, when one building have several addresses.

There was a wide and hot discussion in osm talk mailing list:

https://lists.openstreetmap.org/pipermail/tagging/2015-January/020960.html
https://lists.openstreetmap.org/pipermail/tagging/2015-January/021085.html

So as an option, it would be nice to have an option to return other addresses of the same object, which was found. But I don't know how to add them in a best way.

Use of ISO-3166-1 for country value rather than country name to avoid any ambiguity.

What about adding a field about quality of the result ?

we have noticed that there is already an issue about the admin field: #7, which is partially interesting for us and our opinion is also shared in this very issue.

Another problem we met recently is that we'd like to expose more details in admin field especially coord and id.

final result will look like:

{
    …
    "admin": [
         {
              "type": "country",
              "name": "France",
              "admin_level": 1,
              "coord": "42;42"
         },
         {
              "type": "region",
              "name": "Nord-Pas-de-Calais",
              "admin_level": 2,
              "coord": "42;42"
         },
         {
              "type": "mycustomlevel",
              "name": "Nord",
              "admin_level": 3,
              "coord": "42;42"
         },
    ]
}

I'm working on an OpenAPI spec of Openstreetmap Nominatim API, describing the GeocodeJSON format using JSON Schema.

In #21 @DanielJDufour had already proposed the idea of defining a json schema for gecodejson.

Here you can find a draft of GeocodeJSON schema modeling the spec: https://github.com/jenkin/geocodejson-spec/blob/feature/json-schema/src/geocodejson.schema.json (also deferenced and bundled).

So in a custom schema you can refer to the official one using $ref attribute (ie. in an openapi spec).

{
    "responses": {
        "200": {
            "description": "OK",
            "content": {
                "application/json": {
                    "schema": {
                        "type": "array",
                        "items": {
                            "$ref": "https://geocoders.github.io/geocodejson-spec/draft/geocodejson.schema.json"
                        }
                    }
                }
            }
        }
    }
}

I know this project is quite dormant, but if you want I can open a PR from this branch.

I suggest to put this optional field containing the geographical continent name, following 7 continents model, in the properties.geocoding namespace i.e:

• Europe for Paris, France
• South America for Cayenne, France
• Antartica for -72.0129, 2.5284

This would especially be usefull for addresses where no country can be clearly defined, such as Antartica.

      // OPTIONAL. Geographical continent of the place, following 7 continents model (https://en.wikipedia.org/wiki/Continent#Number).
      "continent": "Europe",

One of the optional properties of carmen-geojson which is probably also needed for several other geocoders, both commercial and open, is attribution, which should note requires for credit and usage of geocoding results.

At Kisio/CanalTP (on navitia API), we are integrating Points Of Interest from osm into our geocoder, trying to stick to the geocodejson-spec as much as possible.
We noticed that you use locality on api-adresse for example on Tour Eiffel, but it seems to vague and not fitting very well, so we would like to introduce poi to the list of possible geocoding.type.
So wanted to discuss about the opportunity of that...

District can be a state district (as in opendagacedata API) or a city district (as in HERE api).
Must be clarified or replaced with other data storage.