API Schemas

These component schemas define the structure of responses and reusable objects in the OpenAPI document. Expand a schema to inspect its JSON shape.

GeoJSONFeatureCollection

object

• • typeRequiredstring
  • geocodingRequiredGeocodingMetadata
  • featuresRequiredarray

    Ordered list of the matched records.

    Items

    • itemOptionalGeoJSONFeature
  • bboxOptionalarray

    Bounding box for all returned features.

    Items

    • itemOptionalnumber (double)

View raw schema JSON

{
  "type": "object",
  "required": [
    "type",
    "geocoding",
    "features"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "FeatureCollection"
    },
    "geocoding": {
      "$ref": "#/components/schemas/GeocodingMetadata"
    },
    "features": {
      "type": "array",
      "description": "Ordered list of the matched records.",
      "items": {
        "$ref": "#/components/schemas/GeoJSONFeature"
      }
    },
    "bbox": {
      "type": "array",
      "description": "Bounding box for all returned features.",
      "minItems": 4,
      "maxItems": 6,
      "items": {
        "type": "number",
        "format": "double"
      }
    }
  }
}

BulkJob

object

• • idRequiredstring (uuid)
  • statusRequiredBulkJobStatus
  • submitted_atRequiredstring (date-time)
  • started_atOptionalstring (date-time)
  • completed_atOptionalstring (date-time)
  • expires_atOptionalstring (date-time)
  • inputRequiredBulkInput
  • callbackRequiredBulkCallback
  • optionsOptionalBulkJobOptions
  • metadataOptionalobject

    No declared properties.

  • statisticsOptionalBulkJobStatistics
  • delivery_attemptsOptionalarray

    Items

    • itemOptionalBulkDeliveryAttempt

View raw schema JSON

{
  "type": "object",
  "required": [
    "id",
    "status",
    "submitted_at",
    "input",
    "callback"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "$ref": "#/components/schemas/BulkJobStatus"
    },
    "submitted_at": {
      "type": "string",
      "format": "date-time"
    },
    "started_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "type": "string",
      "format": "date-time"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "input": {
      "$ref": "#/components/schemas/BulkInput"
    },
    "callback": {
      "$ref": "#/components/schemas/BulkCallback"
    },
    "options": {
      "$ref": "#/components/schemas/BulkJobOptions"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true
    },
    "statistics": {
      "$ref": "#/components/schemas/BulkJobStatistics"
    },
    "delivery_attempts": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BulkDeliveryAttempt"
      }
    }
  }
}

BulkJobResults

object

• • jobRequiredBulkJob
  • formatOptionalstring

    Enum values:

    • geojson
    • ndjson
    • csv
  • cursorOptionalstring

    Cursor for retrieving the next page of results when pagination is required.

  • resultsRequiredany

    oneOf

    • oneOf[0]OptionalGeoJSONFeatureCollection
    • oneOf[1]Optionalstring

      Presigned URL to download results when the payload is too large to inline.

    • oneOf[2]Optionalarray

      Inline newline-delimited JSON entries when `format=ndjson` is requested with a JSON response. Prefer the `application/x-ndjson` response to stream results.

      Items

      • itemOptionalstring

View raw schema JSON

{
  "type": "object",
  "required": [
    "job",
    "results"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    },
    "format": {
      "type": "string",
      "enum": [
        "geojson",
        "ndjson",
        "csv"
      ]
    },
    "cursor": {
      "type": "string",
      "description": "Cursor for retrieving the next page of results when pagination is required."
    },
    "results": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/GeoJSONFeatureCollection"
        },
        {
          "type": "string",
          "description": "Presigned URL to download results when the payload is too large to inline."
        },
        {
          "type": "array",
          "description": "Inline newline-delimited JSON entries when `format=ndjson` is requested with a JSON response. Prefer the `application/x-ndjson` response to stream results.",
          "items": {
            "type": "string"
          }
        }
      ]
    }
  }
}

Problem

object

• • typeOptionalstring (uri)

    Default: about:blank
  • titleRequiredstring
  • statusRequiredinteger
  • detailOptionalstring
  • instanceOptionalstring
  • errorsOptionalarray

    Items

    • itemOptionalobject

      • fieldOptionalstring
      • messageOptionalstring

View raw schema JSON

{
  "type": "object",
  "required": [
    "title",
    "status"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "default": "about:blank"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

PeliasWarning

object

• • codeOptionalstring

    Examples:

    • SIZE_COERCED
  • messageOptionalstring

View raw schema JSON

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "example": "SIZE_COERCED"
    },
    "message": {
      "type": "string"
    }
  }
}

GeocodingMetadata

object

Metadata block returned by Pelias-compatible services.

• • versionOptionalstring

    Examples:

    • 1.0.0
  • attributionOptionalstring

    Attribution text that must be displayed with the data.

  • queryOptionalobject

    Canonical representation of the parsed query.

    No declared properties.

  • engineOptionalobject

    • nameOptionalstring

      Examples:

      • pelias
    • authorOptionalstring
    • versionOptionalstring
  • timestampOptionalstring (date-time)
  • warningsOptionalarray

    Items

    • itemOptionalPeliasWarning
  • errorsOptionalarray

    Items

    • itemOptionalPeliasWarning

View raw schema JSON

{
  "type": "object",
  "description": "Metadata block returned by Pelias-compatible services.",
  "properties": {
    "version": {
      "type": "string",
      "example": "1.0.0"
    },
    "attribution": {
      "type": "string",
      "description": "Attribution text that must be displayed with the data."
    },
    "query": {
      "type": "object",
      "additionalProperties": true,
      "description": "Canonical representation of the parsed query."
    },
    "engine": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "example": "pelias"
        },
        "author": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      }
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PeliasWarning"
      }
    },
    "errors": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PeliasWarning"
      }
    }
  }
}

GeoJSONPoint

object

• • typeRequiredstring
  • coordinatesRequiredarray

    Coordinates expressed as [longitude, latitude].

    Items

    • itemOptionalnumber (double)

View raw schema JSON

{
  "type": "object",
  "required": [
    "type",
    "coordinates"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "Point"
    },
    "coordinates": {
      "type": "array",
      "description": "Coordinates expressed as [longitude, latitude].",
      "minItems": 2,
      "maxItems": 3,
      "items": {
        "type": "number",
        "format": "double"
      }
    }
  }
}

PeliasProperties

object

Core attributes for a Pelias record.

• • idOptionalstring

    Examples:

    • 101750367
  • gidOptionalstring

    Examples:

    • whosonfirst:locality:101750367
  • layerOptionalstring

    Feature layer for the record.

    Enum values:

    • venue
    • address
    • street
    • neighbourhood
    • locality
    • borough
    • localadmin
    • county
    • macrocounty
    • region
    • macroregion
    • country
    • coarse
    • postalcode
  • sourceOptionalstring

    Enum values:

    • openstreetmap
    • openaddresses
    • geonames
    • whosonfirst
    • osm
    • oa
    • gn
    • wof
  • source_idOptionalstring

    Examples:

    • way/5013364
  • nameOptionalstring

    Short display name for the feature.

    Examples:

    • London
  • labelOptionalstring

    Human readable label incorporating hierarchy information.

    Examples:

    • London, England, United Kingdom
  • confidenceOptionalnumber (float)

    Examples:

    • 0.949
  • distanceOptionalnumber (float)

    Distance in kilometers from the query point (reverse only).

  • accuracyOptionalstring

    Accuracy classification for the match.

  • housenumberOptionalstring
  • streetOptionalstring
  • neighbourhoodOptionalstring
  • boroughOptionalstring
  • localityOptionalstring
  • localadminOptionalstring
  • countyOptionalstring
  • macrocountyOptionalstring
  • regionOptionalstring
  • macroregionOptionalstring
  • countryOptionalstring
  • country_gidOptionalstring
  • country_aOptionalstring
  • postalcodeOptionalstring
  • continentOptionalstring
  • categoriesOptionalarray

    Items

    • itemOptionalstring
  • addendumOptionalobject

    Provider-specific metadata.

    No declared properties.

View raw schema JSON

{
  "type": "object",
  "description": "Core attributes for a Pelias record.",
  "properties": {
    "id": {
      "type": "string",
      "example": "101750367"
    },
    "gid": {
      "type": "string",
      "example": "whosonfirst:locality:101750367"
    },
    "layer": {
      "type": "string",
      "description": "Feature layer for the record.",
      "enum": [
        "venue",
        "address",
        "street",
        "neighbourhood",
        "locality",
        "borough",
        "localadmin",
        "county",
        "macrocounty",
        "region",
        "macroregion",
        "country",
        "coarse",
        "postalcode"
      ]
    },
    "source": {
      "type": "string",
      "enum": [
        "openstreetmap",
        "openaddresses",
        "geonames",
        "whosonfirst",
        "osm",
        "oa",
        "gn",
        "wof"
      ]
    },
    "source_id": {
      "type": "string",
      "example": "way/5013364"
    },
    "name": {
      "type": "string",
      "description": "Short display name for the feature.",
      "example": "London"
    },
    "label": {
      "type": "string",
      "description": "Human readable label incorporating hierarchy information.",
      "example": "London, England, United Kingdom"
    },
    "confidence": {
      "type": "number",
      "format": "float",
      "minimum": 0,
      "maximum": 1,
      "example": 0.949
    },
    "distance": {
      "type": "number",
      "format": "float",
      "description": "Distance in kilometers from the query point (reverse only)."
    },
    "accuracy": {
      "type": "string",
      "description": "Accuracy classification for the match."
    },
    "housenumber": {
      "type": "string"
    },
    "street": {
      "type": "string"
    },
    "neighbourhood": {
      "type": "string"
    },
    "borough": {
      "type": "string"
    },
    "locality": {
      "type": "string"
    },
    "localadmin": {
      "type": "string"
    },
    "county": {
      "type": "string"
    },
    "macrocounty": {
      "type": "string"
    },
    "region": {
      "type": "string"
    },
    "macroregion": {
      "type": "string"
    },
    "country": {
      "type": "string"
    },
    "country_gid": {
      "type": "string"
    },
    "country_a": {
      "type": "string"
    },
    "postalcode": {
      "type": "string"
    },
    "continent": {
      "type": "string"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "addendum": {
      "type": "object",
      "additionalProperties": true,
      "description": "Provider-specific metadata."
    }
  }
}

GeoJSONFeature

object

• • typeRequiredstring
  • geometryRequiredGeoJSONPoint
  • propertiesRequiredPeliasProperties
  • bboxOptionalarray

    Items

    • itemOptionalnumber (double)

View raw schema JSON

{
  "type": "object",
  "required": [
    "type",
    "geometry",
    "properties"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "Feature"
    },
    "geometry": {
      "$ref": "#/components/schemas/GeoJSONPoint"
    },
    "properties": {
      "$ref": "#/components/schemas/PeliasProperties"
    },
    "bbox": {
      "type": "array",
      "minItems": 4,
      "maxItems": 6,
      "items": {
        "type": "number",
        "format": "double"
      }
    }
  }
}

BulkJobStatus

string

• Enum values:

  • queued
  • validating
  • processing
  • delivering
  • succeeded
  • failed
  • cancelled

View raw schema JSON

{
  "type": "string",
  "enum": [
    "queued",
    "validating",
    "processing",
    "delivering",
    "succeeded",
    "failed",
    "cancelled"
  ]
}

BulkInlineRecord

object

Single record submitted inline for bulk processing.

• oneOf

  • oneOf[0]Optionalany
  • oneOf[1]Optionalany

  • idRequiredstring

    Client-supplied identifier used to correlate results.

  • textOptionalstring

    Free-form text query. Required when `structured` is not provided.

  • structuredOptionalobject

    Structured search fields mirroring the `/search/structured` endpoint.

    • addressOptionalstring
    • neighbourhoodOptionalstring
    • boroughOptionalstring
    • localityOptionalstring
    • countyOptionalstring
    • regionOptionalstring
    • postalcodeOptionalstring
    • countryOptionalstring
  • sourcesOptionalarray

    Optional override of the sources used for this record.

    Items

    • itemOptionalstring
  • layersOptionalarray

    Optional override of the layers used for this record.

    Items

    • itemOptionalstring

View raw schema JSON

{
  "type": "object",
  "description": "Single record submitted inline for bulk processing.",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Client-supplied identifier used to correlate results."
    },
    "text": {
      "type": "string",
      "description": "Free-form text query. Required when `structured` is not provided."
    },
    "structured": {
      "type": "object",
      "description": "Structured search fields mirroring the `/search/structured` endpoint.",
      "properties": {
        "address": {
          "type": "string"
        },
        "neighbourhood": {
          "type": "string"
        },
        "borough": {
          "type": "string"
        },
        "locality": {
          "type": "string"
        },
        "county": {
          "type": "string"
        },
        "region": {
          "type": "string"
        },
        "postalcode": {
          "type": "string"
        },
        "country": {
          "type": "string"
        }
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional override of the sources used for this record."
    },
    "layers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional override of the layers used for this record."
    }
  },
  "oneOf": [
    {
      "required": [
        "text"
      ]
    },
    {
      "required": [
        "structured"
      ]
    }
  ]
}

BulkInput

object

Location of the bulk payload to be processed.

• oneOf

  • oneOf[0]Optionalany
  • oneOf[1]Optionalany

  • transportRequiredstring

    Transfer mechanism for retrieving the job payload.

    Enum values:

    • https
    • s3
    • inline
  • urlOptionalstring (uri)

    HTTPS or S3 URI that the service will download and process.

  • recordsOptionalarray

    Inline payload for small jobs.

    Items

    • itemOptionalBulkInlineRecord
  • compressionOptionalstring

    Enum values:

    • none
    • gzip
    • zip

    Default: none
  • content_typeOptionalstring

    MIME type describing the payload contents.

  • encodingOptionalstring

    Default: utf-8

View raw schema JSON

{
  "type": "object",
  "description": "Location of the bulk payload to be processed.",
  "required": [
    "transport"
  ],
  "properties": {
    "transport": {
      "type": "string",
      "enum": [
        "https",
        "s3",
        "inline"
      ],
      "description": "Transfer mechanism for retrieving the job payload."
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "HTTPS or S3 URI that the service will download and process."
    },
    "records": {
      "type": "array",
      "description": "Inline payload for small jobs.",
      "maxItems": 1000,
      "items": {
        "$ref": "#/components/schemas/BulkInlineRecord"
      }
    },
    "compression": {
      "type": "string",
      "enum": [
        "none",
        "gzip",
        "zip"
      ],
      "default": "none"
    },
    "content_type": {
      "type": "string",
      "description": "MIME type describing the payload contents."
    },
    "encoding": {
      "type": "string",
      "default": "utf-8"
    }
  },
  "oneOf": [
    {
      "required": [
        "url"
      ]
    },
    {
      "required": [
        "records"
      ]
    }
  ]
}

BulkRetryPolicy

object

• • max_attemptsOptionalinteger

    Default: 5
  • initial_delay_secondsOptionalinteger

    Default: 30
  • strategyOptionalstring

    Enum values:

    • exponential
    • linear
    • fixed

    Default: exponential

View raw schema JSON

{
  "type": "object",
  "properties": {
    "max_attempts": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12,
      "default": 5
    },
    "initial_delay_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3600,
      "default": 30
    },
    "strategy": {
      "type": "string",
      "enum": [
        "exponential",
        "linear",
        "fixed"
      ],
      "default": "exponential"
    }
  }
}

BulkCallback

object

• • urlRequiredstring (uri)

    HTTPS endpoint that will receive job completion notifications.

  • secretRequiredstring

    Shared secret used to compute webhook signatures.

  • signature_headerOptionalstring

    Name of the header that transports the HMAC signature.

    Default: X-Geobridge-Signature
  • replay_window_secondsOptionalinteger

    Time window in seconds in which the receiver must reject duplicate deliveries.

    Default: 300
  • retry_policyOptionalBulkRetryPolicy

View raw schema JSON

{
  "type": "object",
  "required": [
    "url",
    "secret"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "HTTPS endpoint that will receive job completion notifications."
    },
    "secret": {
      "type": "string",
      "minLength": 16,
      "description": "Shared secret used to compute webhook signatures."
    },
    "signature_header": {
      "type": "string",
      "default": "X-Geobridge-Signature",
      "description": "Name of the header that transports the HMAC signature."
    },
    "replay_window_seconds": {
      "type": "integer",
      "default": 300,
      "description": "Time window in seconds in which the receiver must reject duplicate deliveries."
    },
    "retry_policy": {
      "$ref": "#/components/schemas/BulkRetryPolicy"
    }
  }
}

BulkJobOptions

object

• • output_formatOptionalstring

    Enum values:

    • geojson
    • ndjson
    • csv

    Default: geojson
  • truncate_atOptionalinteger

    Optional limit on the number of matches returned per record.

  • keep_intermediate_filesOptionalboolean

    Default: false
  • priorityOptionalstring

    Enum values:

    • normal
    • high
    • low

    Default: normal

View raw schema JSON

{
  "type": "object",
  "properties": {
    "output_format": {
      "type": "string",
      "enum": [
        "geojson",
        "ndjson",
        "csv"
      ],
      "default": "geojson"
    },
    "truncate_at": {
      "type": "integer",
      "minimum": 1,
      "description": "Optional limit on the number of matches returned per record."
    },
    "keep_intermediate_files": {
      "type": "boolean",
      "default": false
    },
    "priority": {
      "type": "string",
      "enum": [
        "normal",
        "high",
        "low"
      ],
      "default": "normal"
    }
  }
}

BulkJobStatistics

object

• • total_recordsOptionalinteger
  • processed_recordsOptionalinteger
  • successful_recordsOptionalinteger
  • failed_recordsOptionalinteger
  • last_record_idOptionalstring

View raw schema JSON

{
  "type": "object",
  "properties": {
    "total_records": {
      "type": "integer",
      "minimum": 0
    },
    "processed_records": {
      "type": "integer",
      "minimum": 0
    },
    "successful_records": {
      "type": "integer",
      "minimum": 0
    },
    "failed_records": {
      "type": "integer",
      "minimum": 0
    },
    "last_record_id": {
      "type": "string"
    }
  }
}

BulkDeliveryAttempt

object

• • attemptOptionalinteger
  • status_codeOptionalinteger
  • delivered_atOptionalstring (date-time)
  • duration_msOptionalinteger
  • errorOptionalstring

View raw schema JSON

{
  "type": "object",
  "properties": {
    "attempt": {
      "type": "integer"
    },
    "status_code": {
      "type": "integer"
    },
    "delivered_at": {
      "type": "string",
      "format": "date-time"
    },
    "duration_ms": {
      "type": "integer"
    },
    "error": {
      "type": "string"
    }
  }
}

BulkJobList

object

• • cursorOptionalstring

    Cursor corresponding to the current page of jobs.

  • jobsOptionalarray

    Items

    • itemOptionalBulkJob
  • next_cursorOptionalstring

    Opaque cursor to fetch the next page of jobs.

View raw schema JSON

{
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "description": "Cursor corresponding to the current page of jobs."
    },
    "jobs": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BulkJob"
      }
    },
    "next_cursor": {
      "type": "string",
      "description": "Opaque cursor to fetch the next page of jobs."
    }
  }
}

BulkJobCreateRequest

object

• • inputRequiredBulkInput
  • callbackRequiredBulkCallback
  • optionsOptionalBulkJobOptions
  • metadataOptionalobject

    Arbitrary key/value pairs echoed back with job status and results.

    No declared properties.

View raw schema JSON

{
  "type": "object",
  "required": [
    "input",
    "callback"
  ],
  "properties": {
    "input": {
      "$ref": "#/components/schemas/BulkInput"
    },
    "callback": {
      "$ref": "#/components/schemas/BulkCallback"
    },
    "options": {
      "$ref": "#/components/schemas/BulkJobOptions"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Arbitrary key/value pairs echoed back with job status and results."
    }
  }
}

BulkJobResponse

any

• allOf

  • allOf[0]OptionalBulkJob

View raw schema JSON

{
  "allOf": [
    {
      "$ref": "#/components/schemas/BulkJob"
    }
  ]
}