Please be aware that the Cartesius API and therefore also this package is currently in public beta. We intend to release a stable v1 of the API mid-2023! In the meantime you can reach out to us if you have any questions ([email protected])

You are just looking for the complete documentation? Click here! If you are looking for ready to use Geo-search/Autocomplete components, check out @cartesius/components (coming soon!)

Usage

If you do not have an API-Key, you can simply create one here.

  yarn add @cartesius/sdk # or
  npm i @cartesius/sdk

You can safely use this package in the browser or with Node.js. Bun and Deno should work as well but are currently not supported.

import { CartesiusClient } from "@cartesius/sdk" // ESM or
const { CartesiusClient } = require("@cartesius/sdk") // CJS

const client = new CartesiusClient({
  apiKey: '<YOUR-API-KEY>',
});

const result = await client.autocomplete("Freiheitsst", {
  languages: ["deu", "en"], // ISO 3166 ALPHA-2 or ALPHA-3
  fields: ["shape", "displayValue", "category"],
  // ... check documentation for detailed overview of options
})

Result would look like this (CartesiusApiResponse<CartesiusGeoFeature[]>). For a detailed schema of the Cartesius Geo-Feature click here.

{
  "code": 200,
  "status": "success",
  "data": [
    {
      "id": "3af175223969876389ee96a0bf1a29ad",
      "type": "Feature",
      "bbox": [-74.04510690000001, 40.6888049, -74.0439637, 40.689674100000005],
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-74.045004, 40.6892215],
            [-74.04510230000001, 40.6891073],
            [-74.0449107, 40.689072100000004],
            ...
          ]
        ]
      },
      "properties": {
        "centroid": {
          "geometry": {
            "coordinates": [-74.04454394214909, 40.689244288823055],
            "type": "Point"
          },
          "accuracy": "centroid"
        },
        "displayValue": {
          "local": "Statue of Liberty, New York, 10004, United States of America",
          "abbreviation": "Statue of Liberty, NYC, 10004, USA",
          "eng": "Statue of Liberty, New York, 10004, United States of America",
          "deu": "Freiheitsstatue, New York City, 10004, Vereinigte Staaten"
        },
        "category": { "type": "tourism", "specification": "attraction" },
        ...

The package is non-throwing, every error will be represented as CartesiusApiResponse. Success is being indicated with the status property and the HTTP Status code code. If there has been an error with the request on the client side, the response will have the code -1. Check the messages for a detailed error descriptions.

Documentation

The complete documentation with examples for all features can be found here.