Unofficial OpenAPI Specification (OAS) for Nominatim API provided by OpenStreetMap project (OSM).
Open sparkfabrik.github.io/nominatim-openapi in a browser. Choose the endpoint you are interested in and click on "Try it out". Fill all needed options and click on "Execute", you can see query and results under the "Responses" section.
You can download the formal API specification from here: sparkfabrik.github.io/nominatim-openapi/nominatim.openapi.json.
Nominatim by OpenStreetMap is one of the best FOSS alternative for geolocation tasks, both as a service and self-hosted.
Exposed API is well documented by the official documentation, but it lacks a formal specification such as the well-known OpenAPI (a de-facto standard for REST API).
Some drawbacks of actual API implementation (waiting for version 2, see the planning board) can not be represented by OpenAPI and JSON Schema specifications, but we think that also a partial description can be very useful for end-users and developers (think about code generators for client and server).
This project aims to fill the hole and offer to community a robust, modern, and machine-readable description of the Nominatim API.
Getting started section shows how to use the official interactive playground hosted by Github Pages.
If you want to locally run your own playground, you must download this repository (via zip download or git clone).
Source of OAS is in
src/folder, all final files (bundled and minified) are indocs/folder.
You can't simply open the docs/index.html file in your browser, because of default Cross-Origin Policy.
So you need to serve docs/ folder using a web server running locally.
In a javascript-ready environment (ie. with node and npm installed),
you can run make serve in a terminal from the project folder and point your browser to http://localhost:8080.
In a Docker-ready environment, you can run make ui to have the playground exposed on http://localhost:8091.
You can verify the integrity of deployed spec using the sha512 checksum provided.
You can run make checksum and make verify to compute and verify the checksum.
Refs: #6.
This spec follows the Nominatim API versioning, so it use the same tags of the original project.
A this early stage, we are discussing the roadmap in a dedicated issue. When ready, the following table will be updated.
| Milestone | Task | TBD | To do | Doing | Done | Refs |
|---|---|---|---|---|---|---|
| OpenAPI Spec | /search endpoint |
■ | #2 | |||
/lookup endpoint |
■ | #4 | ||||
/reverse endpoint |
■ | #3 | ||||
/status endpoint |
■ | #5 | ||||
/details endpoint |
■ | #13 | ||||
/deletable endpoint |
■ | #13 | ||||
/polygons endpoint |
■ | #13 | ||||
| Test suite | ■ | |||||
| Node CLI | ■ |
Any contribution is welcome!
Please read and accept our Code of Conduct, then refer to Contributing Guidelines before opening issues or pull requests.
First of all, search for issues or open one to share your thoughts, needs or intents with the maintainers and the community.
Then fork and clone this repo, make your changes, commit and push them on a new branch, finally open a PR against main branch of this repo.
Pre-requisites: git, make, shasum, npx (node and npm), docker.
Editable source of OAS is in src/ folder. You can validate it running make validate. You can bundle it running make build.
Please activate the Git Hooks provided in .githooks/ folder before the first change (hooks are bash scripts). You can simply run make hooks to activate them.
- pre-commit - validate and bundle OAS spec, compute sha512 checksums.
- pre-push - verify the checksums.
In a Docker-ready environment, you can run make editor to have the new Swagger Editor up and running on http://localhost:8092.
Automatic file loading and saving is not available, so you must copy/paste the content of src/nominatim.openapi.json in the editor and then copy/paste it back to save the changes.
Website: https://www.openapis.org
Repository: https://github.com/oai
Also known as: Swagger (see history)
Latest version: v3.1.0
The OpenAPI Specification (OAS) is a specification language for HTTP APIs that provides a standardized means to define your API to others. You can quickly discover how an API works, configure infrastructure, generate client code, and create test cases for your APIs. Read more about how you can get control of your APIs now, understand the full API lifecycle and communicate with developer communities inside and outside your organization.
Website: https://json-schema.org
Repository: https://github.com/json-schema-org
Latest version: v2020-12
JSON Schema enables the confident and reliable use of the JSON data format.
Website: https://swagger.io/tools/swagger-ui/
Repository: https://github.com/swagger-api/swagger-ui
Latest version: v5.1.0
Swagger UI allows anyone - be it your development team or your end consumers - to visualize and interact with the API's resources without having any of the implementation logic in place. It's automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.
Website: https://www.openstreetmap.org
Repository: https://github.com/openstreetmap
OpenStreetMap is a map of the world, created by people like you and free to use under an open license. It is built by a community of mappers that contribute and maintain data about roads, trails, cafés, railway stations, and much more, all over the world.
Website: https://nominatim.org
Repository: https://github.com/osm-search
Nominatim uses OpenStreetMap data to find locations on Earth by name and address (geocoding). It can also do the reverse, find an address for any location on the planet.
Website: https://geojson.org
Repository: https://github.com/geojson
GeoJSON is a format for encoding a variety of geographic data structures.
Website: https://github.com/geocoders/geocodejson-spec/tree/master/draft
Repository: https://github.com/geocoders/geocodejson-spec
This specification attempts to create a standard for handling geocoding results.
Website: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
Subresource Integrity (SRI) is a security feature that enables browsers to verify that resources they fetch e delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match.
Website: https://en.wikipedia.org/wiki/SHA-2
The Secure Hash Algorithms are a family of cryptographic hash functions published by the National Institute of Standards and Technology (NIST).
Nominatim (and OpenStreetMap) project have a long story and a non trivial development path, so this OpenAPI specification reflects some features of actual software and official documentation.
- The
formatparameter (docs) accepts 5 values (xml,json,jsonv2,geojson,geocodejson), wherejsonv2is the default one, but this specification describes only thegeocodejsonformat incomponents.schemas(see Nominatim/discussions/3115, Nominatim/issues/1697, and OpenAPI-Specification/issues/2031 for further informations).
This project would not exist without open source, it is open source, and the community behind it contributes to open source.
Here is a list of external contributions (code and discussions) starting from work for this project:
- release of the official schema for
geocodejsonspec: geocodejson-spec/pull/25 (see also geocodejson-spec/issues/21) - fix typos in Nominatim error messages: Nominatim/pull/3112
- release of an unofficial schema for GeoHash format (see jenkin/json-schema-bricks)
- release of an unofficial schema for SemVer format (see jenkin/json-schema-bricks)
- discussion about
jsonv2andgeocodejsonformats of Nominatim responses: Nominatim/discussions/3115 - ...
MIT license on OpenAPI Specification. Geolocated data from OSM are provided under the ODbL license. Please read and accept the Nominatim Usage Policy before any use.
Many thanks to all OpenStreetMap contributors.
Pictures for this project are generated using Midjourney.
