{
"openapi": "3.1.0",
"info": {
"title": "Geocoder.ca API",
"version": "2026-09-23",
"summary": "Geocoding, reverse geocoding, address validation, postal code/ZIP lookup, geoparsing and places for Canada and the USA.",
"description": "Independent North American geocoding API operated by Geolytica Inc. (Ottawa, Canada) since 2005. Canadian results can include Statistics Canada dissemination areas, time zone, area code and Alberta Township System legal subdivisions. Full human-readable documentation: https://geocoder.ca/api",
"termsOfService": "https://geocoder.ca/terms",
"contact": {
"name": "Geocoder.ca",
"url": "https://geocoder.ca/contact",
"email": "geodata@geocoder.ca"
}
},
"externalDocs": {
"description": "API documentation",
"url": "https://geocoder.ca/api"
},
"servers": [
{
"url": "https://geocoder.ca",
"description": "Production"
}
],
"tags": [
{
"name": "Geocoding",
"description": "All functions share one endpoint"
}
],
"paths": {
"/": {
"get": {
"tags": [
"Geocoding"
],
"parameters": [
{
"name": "geoit",
"in": "query",
"required": false,
"description": "Output port. `XML` for XML (add `json=1` for JSON, `jsonp=1` for JSONP) or `CSV`. Required for machine-readable output; without it the HTML page is returned.",
"schema": {
"type": "string",
"enum": [
"XML",
"CSV",
"xml",
"csv"
]
},
"example": "XML"
},
{
"name": "json",
"in": "query",
"required": false,
"description": "Return JSON instead of XML (use with `geoit=XML`).",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "jsonp",
"in": "query",
"required": false,
"description": "Return JSONP; supply the function name in `callback`.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "callback",
"in": "query",
"required": false,
"description": "JSONP callback function name (with `jsonp=1`).",
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "query",
"required": false,
"description": "Your transaction id (up to 15 bytes), echoed back in the response.",
"schema": {
"type": "string"
}
},
{
"name": "decimal",
"in": "query",
"required": false,
"description": "Limit the number of decimal places in returned coordinates.",
"schema": {
"type": "integer"
}
},
{
"name": "locate",
"in": "query",
"required": false,
"description": "Location to geocode: street address, intersection (e.g. `metcalfe & wellington ottawa`), Canadian postal code, US ZIP / ZIP+4, IP address, or a free-form combination. Include as much detail as possible.",
"schema": {
"type": "string"
},
"example": "330 metcalfe ottawa on"
},
{
"name": "standard",
"in": "query",
"required": false,
"description": "Return the standardized address components (stnumber, staddress, city, prov, postal).",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "strict",
"in": "query",
"required": false,
"description": "Strict parsing of free-form input.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "strictmode",
"in": "query",
"required": false,
"description": "If 1, do not guess on ambiguous input (e.g. a city name without a province/state); return suggestions instead.",
"schema": {
"type": "integer",
"enum": [
0,
1
]
}
},
{
"name": "topmatches",
"in": "query",
"required": false,
"description": "For partial or malformed input, return up to this many best candidate matches.",
"schema": {
"type": "integer"
},
"example": 5
},
{
"name": "showpostal",
"in": "query",
"required": false,
"description": "Also return the postal code / ZIP for an address or intersection.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "showcountry",
"in": "query",
"required": false,
"description": "Also return the country code (`CA` or `US`).",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "showaddrs",
"in": "query",
"required": false,
"description": "Premium, billed per address: for a postal code / ZIP, return all associated civic addresses. Use with `limit` and optionally `street`.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Maximum number of addresses returned by `showaddrs`.",
"schema": {
"type": "integer"
},
"example": 100
},
{
"name": "street",
"in": "query",
"required": false,
"description": "Restrict `showaddrs` results to this street name.",
"schema": {
"type": "string"
}
},
{
"name": "bounds",
"in": "query",
"required": false,
"description": "Bias results to a bounding box (south-west and north-east corners, comma-separated). Applies to `locate` and `scantext`.",
"schema": {
"type": "string"
}
},
{
"name": "country",
"in": "query",
"required": false,
"description": "Bias results to one country.",
"schema": {
"type": "string",
"enum": [
"canada",
"usa"
]
}
},
{
"name": "region",
"in": "query",
"required": false,
"description": "Limit results to a 2-letter province/state code (e.g. `ON`, `NY`) or to `canada` / `usa`.",
"schema": {
"type": "string"
},
"example": "ON"
},
{
"name": "utm",
"in": "query",
"required": false,
"description": "Also return UTM coordinates.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "postal",
"in": "query",
"required": false,
"description": "Deprecated: a Canadian postal code (ANANAN) or US ZIP5 / ZIP+4. Prefer `locate`. With `standard=1&moreinfo=1` it also performs a postal-code reverse lookup.",
"schema": {
"type": "string"
},
"example": "K2P1S4"
},
{
"name": "getpolygon",
"in": "query",
"required": false,
"description": "Return the postal-code boundary polygon for the matched postal code.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "scantext",
"in": "query",
"required": false,
"description": "Geoparsing: free-form text containing one or more North American locations. Every location found is returned in `match[]`, ordered by confidence.",
"schema": {
"type": "string"
},
"example": "Meet me at 330 Metcalfe St, Ottawa, then 100 Queen St W, Toronto"
},
{
"name": "latt",
"in": "query",
"required": false,
"description": "Latitude (decimal degrees) for reverse geocoding (with `reverse=1`).",
"schema": {
"type": "number"
},
"example": 45.4215
},
{
"name": "longt",
"in": "query",
"required": false,
"description": "Longitude (decimal degrees) for reverse geocoding (with `reverse=1`).",
"schema": {
"type": "number"
},
"example": -75.6972
},
{
"name": "reverse",
"in": "query",
"required": false,
"description": "Reverse-geocoding mode: return the nearest civic address, postal code, intersections and closest road for `latt`/`longt`.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "allna",
"in": "query",
"required": false,
"description": "Search both Canada and the USA. Required for reverse geocoding US points; near the border two results may be returned.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "corner",
"in": "query",
"required": false,
"description": "Reverse: also return the nearest street intersection.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "moreinfo",
"in": "query",
"required": false,
"description": "Reverse: add county and metro-area information.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "range",
"in": "query",
"required": false,
"description": "Reverse: limit the search radius.",
"schema": {
"type": "number"
}
},
{
"name": "exact",
"in": "query",
"required": false,
"description": "Reverse: attempt an exact (rooftop) match.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "nopostal",
"in": "query",
"required": false,
"description": "Reverse: ignore the postal code; street-level match only.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "pois",
"in": "query",
"required": false,
"description": "With a reverse lookup, also return nearby points of interest.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "type",
"in": "query",
"required": false,
"description": "Place category for `pois=1`, e.g. `restaurant`.",
"schema": {
"type": "string"
},
"example": "restaurant"
},
{
"name": "keyword",
"in": "query",
"required": false,
"description": "Place keyword for `pois=1`, e.g. `Subway`. When set, `type` is ignored.",
"schema": {
"type": "string"
}
},
{
"name": "radius",
"in": "query",
"required": false,
"description": "Place-search radius in metres. Omit to auto-size (up to about 1.5 km).",
"schema": {
"type": "integer"
}
},
{
"name": "cross",
"in": "query",
"required": false,
"description": "Intersection mode: geocode the crossing of `street1` and `street2` in `city`, `prov`.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "street1",
"in": "query",
"required": false,
"description": "Intersection: first street name (up to 220 bytes).",
"schema": {
"type": "string"
}
},
{
"name": "street2",
"in": "query",
"required": false,
"description": "Intersection: second street name (up to 220 bytes).",
"schema": {
"type": "string"
}
},
{
"name": "city",
"in": "query",
"required": false,
"description": "Intersection: city name (up to 220 bytes).",
"schema": {
"type": "string"
}
},
{
"name": "prov",
"in": "query",
"required": false,
"description": "Intersection: 2-letter Canadian province/territory or US state code.",
"schema": {
"type": "string"
},
"example": "ON"
},
{
"name": "autocomplete",
"in": "query",
"required": false,
"description": "Premium subscription: Canadian postal-address autocomplete for the partial address in `locate`.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "batchpostal",
"in": "query",
"required": false,
"description": "Premium, billed per code: multiple postal codes separated by `|`.",
"schema": {
"type": "string"
},
"example": "K2C1N5|K2P1S4"
},
{
"name": "postalinpolygon",
"in": "query",
"required": false,
"description": "Premium, billed per code: return all postal codes inside a polygon given as pipe-separated vertices.",
"schema": {
"type": "string"
}
},
{
"name": "censusdatafromdauid",
"in": "query",
"required": false,
"description": "Premium, billed per item: Statistics Canada census data for a dissemination area id (`dauid`) returned by a previous lookup.",
"schema": {
"type": "string"
},
"example": "59350105"
},
{
"name": "boundary",
"in": "query",
"required": false,
"description": "Premium, CSV only: neighbourhood boundary lookup as `Name,City,lat,lng` (use with `geoit=CSV`).",
"schema": {
"type": "string"
}
},
{
"name": "matchonly",
"in": "query",
"required": false,
"description": "Partial street-name matching mode; use with `cityname`, `provname`, `streetname` (or `bounds`).",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "cityname",
"in": "query",
"required": false,
"description": "Street matching: city name.",
"schema": {
"type": "string"
},
"example": "Ottawa"
},
{
"name": "provname",
"in": "query",
"required": false,
"description": "Street matching: 2-letter province/state code.",
"schema": {
"type": "string"
},
"example": "on"
},
{
"name": "streetname",
"in": "query",
"required": false,
"description": "Street matching: partial street name.",
"schema": {
"type": "string"
},
"example": "metcalfe"
}
],
"responses": {
"200": {
"description": "Result (or an application-level error object with code 00x). Format depends on `geoit`, `json` and `jsonp`.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/GeocodeResult"
},
{
"$ref": "#/components/schemas/GeoparseResult"
},
{
"$ref": "#/components/schemas/Error"
}
]
},
"examples": {
"forward": {
"summary": "330 metcalfe ottawa on, standard=1, showpostal=1",
"value": {
"latt": "45.414399",
"longt": "-75.690474",
"postal": "K2P1S4",
"standard": {
"stnumber": "330",
"staddress": "Metcalfe",
"city": "Ottawa",
"prov": "ON",
"confidence": "1"
},
"Dissemination_Area": {
"dauid": "35061714",
"adauid": "35060135"
}
}
}
}
},
"text/xml": {
"schema": {
"type": "string"
},
"example": "45.414399-75.690474..."
},
"text/csv": {
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Rate limited (error code 006). Unauthenticated requests are throttled; use an auth token. Honour `Retry-After` when present.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds to wait before retrying"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"success": false,
"error": {
"code": "006",
"message": "Request Throttled. Over Rate limit: up to 2 per sec. See geocoder.ca/pricing"
}
}
},
"text/xml": {
"schema": {
"type": "string"
}
}
}
}
},
"security": [
{},
{
"authToken": []
}
],
"operationId": "geocode",
"summary": "Geocode, reverse geocode, geoparse or look up places",
"description": "Single endpoint; the mode is chosen by parameters:\n\n- **Forward geocoding / address validation**: `locate` (+ `standard=1`, `showpostal=1`)\n- **Reverse geocoding**: `latt`, `longt`, `reverse=1` (+ `allna=1` for US points, `corner=1`, `moreinfo=1`)\n- **Nearby places**: reverse lookup + `pois=1` (+ `type`, `keyword`, `radius`)\n- **Intersection**: `street1`, `street2`, `city`, `prov`, `cross=1`\n- **Geoparsing**: `scantext`\n- **Street-name matching**: `cityname`, `provname`, `streetname`, `matchonly=1`\n- **Premium**: `autocomplete`, `showaddrs`, `batchpostal`, `postalinpolygon`, `censusdatafromdauid`, `boundary`\n\nAlways send `geoit=XML` (with `json=1` for JSON) or `geoit=CSV`. One successful lookup costs one credit; premium functions bill per returned item."
},
"post": {
"tags": [
"Geocoding"
],
"operationId": "geocodePost",
"summary": "Same as GET, with parameters in a form body",
"description": "Accepts the same parameters as `GET /`, sent as `application/x-www-form-urlencoded`. Useful for long `scantext` input.",
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"geoit": {
"type": "string",
"enum": [
"XML",
"CSV",
"xml",
"csv"
],
"description": "Output port. `XML` for XML (add `json=1` for JSON, `jsonp=1` for JSONP) or `CSV`. Required for machine-readable output; without it the HTML page is returned."
},
"json": {
"type": "integer",
"enum": [
1
],
"description": "Return JSON instead of XML (use with `geoit=XML`)."
},
"jsonp": {
"type": "integer",
"enum": [
1
],
"description": "Return JSONP; supply the function name in `callback`."
},
"callback": {
"type": "string",
"description": "JSONP callback function name (with `jsonp=1`)."
},
"id": {
"type": "string",
"description": "Your transaction id (up to 15 bytes), echoed back in the response."
},
"decimal": {
"type": "integer",
"description": "Limit the number of decimal places in returned coordinates."
},
"locate": {
"type": "string",
"description": "Location to geocode: street address, intersection (e.g. `metcalfe & wellington ottawa`), Canadian postal code, US ZIP / ZIP+4, IP address, or a free-form combination. Include as much detail as possible."
},
"standard": {
"type": "integer",
"enum": [
1
],
"description": "Return the standardized address components (stnumber, staddress, city, prov, postal)."
},
"strict": {
"type": "integer",
"enum": [
1
],
"description": "Strict parsing of free-form input."
},
"strictmode": {
"type": "integer",
"enum": [
0,
1
],
"description": "If 1, do not guess on ambiguous input (e.g. a city name without a province/state); return suggestions instead."
},
"topmatches": {
"type": "integer",
"description": "For partial or malformed input, return up to this many best candidate matches."
},
"showpostal": {
"type": "integer",
"enum": [
1
],
"description": "Also return the postal code / ZIP for an address or intersection."
},
"showcountry": {
"type": "integer",
"enum": [
1
],
"description": "Also return the country code (`CA` or `US`)."
},
"showaddrs": {
"type": "integer",
"enum": [
1
],
"description": "Premium, billed per address: for a postal code / ZIP, return all associated civic addresses. Use with `limit` and optionally `street`."
},
"limit": {
"type": "integer",
"description": "Maximum number of addresses returned by `showaddrs`."
},
"street": {
"type": "string",
"description": "Restrict `showaddrs` results to this street name."
},
"bounds": {
"type": "string",
"description": "Bias results to a bounding box (south-west and north-east corners, comma-separated). Applies to `locate` and `scantext`."
},
"country": {
"type": "string",
"enum": [
"canada",
"usa"
],
"description": "Bias results to one country."
},
"region": {
"type": "string",
"description": "Limit results to a 2-letter province/state code (e.g. `ON`, `NY`) or to `canada` / `usa`."
},
"utm": {
"type": "integer",
"enum": [
1
],
"description": "Also return UTM coordinates."
},
"postal": {
"type": "string",
"description": "Deprecated: a Canadian postal code (ANANAN) or US ZIP5 / ZIP+4. Prefer `locate`. With `standard=1&moreinfo=1` it also performs a postal-code reverse lookup."
},
"getpolygon": {
"type": "integer",
"enum": [
1
],
"description": "Return the postal-code boundary polygon for the matched postal code."
},
"scantext": {
"type": "string",
"description": "Geoparsing: free-form text containing one or more North American locations. Every location found is returned in `match[]`, ordered by confidence."
},
"latt": {
"type": "number",
"description": "Latitude (decimal degrees) for reverse geocoding (with `reverse=1`)."
},
"longt": {
"type": "number",
"description": "Longitude (decimal degrees) for reverse geocoding (with `reverse=1`)."
},
"reverse": {
"type": "integer",
"enum": [
1
],
"description": "Reverse-geocoding mode: return the nearest civic address, postal code, intersections and closest road for `latt`/`longt`."
},
"allna": {
"type": "integer",
"enum": [
1
],
"description": "Search both Canada and the USA. Required for reverse geocoding US points; near the border two results may be returned."
},
"corner": {
"type": "integer",
"enum": [
1
],
"description": "Reverse: also return the nearest street intersection."
},
"moreinfo": {
"type": "integer",
"enum": [
1
],
"description": "Reverse: add county and metro-area information."
},
"range": {
"type": "number",
"description": "Reverse: limit the search radius."
},
"exact": {
"type": "integer",
"enum": [
1
],
"description": "Reverse: attempt an exact (rooftop) match."
},
"nopostal": {
"type": "integer",
"enum": [
1
],
"description": "Reverse: ignore the postal code; street-level match only."
},
"pois": {
"type": "integer",
"enum": [
1
],
"description": "With a reverse lookup, also return nearby points of interest."
},
"type": {
"type": "string",
"description": "Place category for `pois=1`, e.g. `restaurant`."
},
"keyword": {
"type": "string",
"description": "Place keyword for `pois=1`, e.g. `Subway`. When set, `type` is ignored."
},
"radius": {
"type": "integer",
"description": "Place-search radius in metres. Omit to auto-size (up to about 1.5 km)."
},
"cross": {
"type": "integer",
"enum": [
1
],
"description": "Intersection mode: geocode the crossing of `street1` and `street2` in `city`, `prov`."
},
"street1": {
"type": "string",
"description": "Intersection: first street name (up to 220 bytes)."
},
"street2": {
"type": "string",
"description": "Intersection: second street name (up to 220 bytes)."
},
"city": {
"type": "string",
"description": "Intersection: city name (up to 220 bytes)."
},
"prov": {
"type": "string",
"description": "Intersection: 2-letter Canadian province/territory or US state code."
},
"autocomplete": {
"type": "integer",
"enum": [
1
],
"description": "Premium subscription: Canadian postal-address autocomplete for the partial address in `locate`."
},
"batchpostal": {
"type": "string",
"description": "Premium, billed per code: multiple postal codes separated by `|`."
},
"postalinpolygon": {
"type": "string",
"description": "Premium, billed per code: return all postal codes inside a polygon given as pipe-separated vertices."
},
"censusdatafromdauid": {
"type": "string",
"description": "Premium, billed per item: Statistics Canada census data for a dissemination area id (`dauid`) returned by a previous lookup."
},
"boundary": {
"type": "string",
"description": "Premium, CSV only: neighbourhood boundary lookup as `Name,City,lat,lng` (use with `geoit=CSV`)."
},
"matchonly": {
"type": "integer",
"enum": [
1
],
"description": "Partial street-name matching mode; use with `cityname`, `provname`, `streetname` (or `bounds`)."
},
"cityname": {
"type": "string",
"description": "Street matching: city name."
},
"provname": {
"type": "string",
"description": "Street matching: 2-letter province/state code."
},
"streetname": {
"type": "string",
"description": "Street matching: partial street name."
},
"auth": {
"type": "string",
"description": "Your auth token"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Result (or an application-level error object with code 00x). Format depends on `geoit`, `json` and `jsonp`.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/GeocodeResult"
},
{
"$ref": "#/components/schemas/GeoparseResult"
},
{
"$ref": "#/components/schemas/Error"
}
]
},
"examples": {
"forward": {
"summary": "330 metcalfe ottawa on, standard=1, showpostal=1",
"value": {
"latt": "45.414399",
"longt": "-75.690474",
"postal": "K2P1S4",
"standard": {
"stnumber": "330",
"staddress": "Metcalfe",
"city": "Ottawa",
"prov": "ON",
"confidence": "1"
},
"Dissemination_Area": {
"dauid": "35061714",
"adauid": "35060135"
}
}
}
}
},
"text/xml": {
"schema": {
"type": "string"
},
"example": "45.414399-75.690474..."
},
"text/csv": {
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Rate limited (error code 006). Unauthenticated requests are throttled; use an auth token. Honour `Retry-After` when present.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds to wait before retrying"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"success": false,
"error": {
"code": "006",
"message": "Request Throttled. Over Rate limit: up to 2 per sec. See geocoder.ca/pricing"
}
}
},
"text/xml": {
"schema": {
"type": "string"
}
}
}
}
},
"security": [
{},
{
"authToken": []
}
]
}
},
"/{location}": {
"get": {
"tags": [
"Geocoding"
],
"operationId": "geocodeShortcut",
"summary": "Shortcut form: location in the path",
"description": "`https://geocoder.ca/{location}?geoit=XML&json=1` geocodes the path segment, e.g. a postal code (`/K1A0A6`), ZIP (`/90210`) or coordinates (`/45.4215,-75.6972`). Accepts the same query parameters as `GET /`. Failed lookups return HTTP 404.",
"parameters": [
{
"name": "location",
"in": "path",
"required": true,
"description": "Location, URL-encoded",
"schema": {
"type": "string"
},
"example": "K1A0A6"
},
{
"name": "geoit",
"in": "query",
"required": false,
"description": "Output port. `XML` for XML (add `json=1` for JSON, `jsonp=1` for JSONP) or `CSV`. Required for machine-readable output; without it the HTML page is returned.",
"schema": {
"type": "string",
"enum": [
"XML",
"CSV",
"xml",
"csv"
]
},
"example": "XML"
},
{
"name": "json",
"in": "query",
"required": false,
"description": "Return JSON instead of XML (use with `geoit=XML`).",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "jsonp",
"in": "query",
"required": false,
"description": "Return JSONP; supply the function name in `callback`.",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "callback",
"in": "query",
"required": false,
"description": "JSONP callback function name (with `jsonp=1`).",
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "query",
"required": false,
"description": "Your transaction id (up to 15 bytes), echoed back in the response.",
"schema": {
"type": "string"
}
},
{
"name": "decimal",
"in": "query",
"required": false,
"description": "Limit the number of decimal places in returned coordinates.",
"schema": {
"type": "integer"
}
},
{
"name": "standard",
"in": "query",
"required": false,
"description": "Return the standardized address components (stnumber, staddress, city, prov, postal).",
"schema": {
"type": "integer",
"enum": [
1
]
}
},
{
"name": "showpostal",
"in": "query",
"required": false,
"description": "Also return the postal code / ZIP for an address or intersection.",
"schema": {
"type": "integer",
"enum": [
1
]
}
}
],
"responses": {
"200": {
"description": "Result (or an application-level error object with code 00x). Format depends on `geoit`, `json` and `jsonp`.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/GeocodeResult"
},
{
"$ref": "#/components/schemas/GeoparseResult"
},
{
"$ref": "#/components/schemas/Error"
}
]
},
"examples": {
"forward": {
"summary": "330 metcalfe ottawa on, standard=1, showpostal=1",
"value": {
"latt": "45.414399",
"longt": "-75.690474",
"postal": "K2P1S4",
"standard": {
"stnumber": "330",
"staddress": "Metcalfe",
"city": "Ottawa",
"prov": "ON",
"confidence": "1"
},
"Dissemination_Area": {
"dauid": "35061714",
"adauid": "35060135"
}
}
}
}
},
"text/xml": {
"schema": {
"type": "string"
},
"example": "45.414399-75.690474..."
},
"text/csv": {
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Rate limited (error code 006). Unauthenticated requests are throttled; use an auth token. Honour `Retry-After` when present.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds to wait before retrying"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"success": false,
"error": {
"code": "006",
"message": "Request Throttled. Over Rate limit: up to 2 per sec. See geocoder.ca/pricing"
}
}
},
"text/xml": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "No match for the location"
}
},
"security": [
{},
{
"authToken": []
}
]
}
}
},
"components": {
"schemas": {
"StandardAddress": {
"type": "object",
"description": "Standardized address (returned with `standard=1`). Values are strings.",
"properties": {
"stnumber": {
"type": "string",
"description": "Civic number"
},
"staddress": {
"type": "string",
"description": "Street name"
},
"city": {
"type": "string",
"description": "City"
},
"prov": {
"type": "string",
"description": "2-letter province or state"
},
"postal": {
"type": "string",
"description": "Postal code or ZIP"
},
"confidence": {
"type": "string",
"description": "Match confidence from 0 to 1, as a string"
}
},
"additionalProperties": true
},
"GeocodeResult": {
"type": "object",
"description": "Forward or reverse geocoding result. All values are returned as strings. Empty `latt`/`longt` means no match.",
"properties": {
"latt": {
"type": "string",
"description": "Latitude"
},
"longt": {
"type": "string",
"description": "Longitude"
},
"postal": {
"type": "string",
"description": "Postal code or ZIP (with showpostal=1)"
},
"standard": {
"$ref": "#/components/schemas/StandardAddress"
},
"Dissemination_Area": {
"type": "object",
"description": "Statistics Canada census geography",
"properties": {
"dauid": {
"type": "string",
"description": "Dissemination area id; feed to censusdatafromdauid"
},
"adauid": {
"type": "string",
"description": "Aggregate dissemination area id"
}
}
},
"TimeZone": {
"type": "string",
"description": "Time zone"
},
"AreaCode": {
"type": "string",
"description": "Telephone area code"
},
"LSD": {
"type": "string",
"description": "Alberta Township System legal subdivision, where applicable"
},
"more": {
"type": "string",
"description": "Part of the input not used for the location, e.g. apartment/unit numbers or PO boxes"
},
"remaining_credits": {
"type": "string",
"description": "Credits left on the auth token"
},
"id": {
"type": "string",
"description": "Your transaction id, if supplied"
},
"inlatt": {
"type": "string",
"description": "Reverse: input latitude"
},
"inlongt": {
"type": "string",
"description": "Reverse: input longitude"
},
"distance": {
"type": "string",
"description": "Reverse: distance from input point"
},
"NearRoad": {
"type": "string",
"description": "Reverse: nearest road"
},
"NearRoadDistance": {
"type": "string",
"description": "Reverse: distance to nearest road"
},
"neighborhood": {
"type": "string",
"description": "Reverse: neighbourhood"
}
},
"additionalProperties": true
},
"GeoparseMatch": {
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "CA or US"
},
"stnumber": {
"type": "string",
"description": "Civic number"
},
"staddress": {
"type": "string",
"description": "Street"
},
"city": {
"type": "string",
"description": "City"
},
"prov": {
"type": "string",
"description": "Province/state"
},
"latt": {
"type": "string",
"description": "Latitude"
},
"longt": {
"type": "string",
"description": "Longitude"
},
"confidence": {
"type": "string",
"description": "Confidence 0-1"
}
},
"additionalProperties": true
},
"GeoparseResult": {
"type": "object",
"description": "Result of `scantext` geoparsing: every location found, highest confidence first.",
"properties": {
"match": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GeoparseMatch"
}
},
"latt": {
"type": "string",
"description": "Centroid latitude of matches"
},
"longt": {
"type": "string",
"description": "Centroid longitude of matches"
},
"remaining_credits": {
"type": "string",
"description": "Credits left"
}
},
"additionalProperties": true
},
"Error": {
"type": "object",
"description": "Error response. Codes: 001 IP not allowed for this token; 002 token out of credits; 003 token not found; 004 invalid province/state code; 005 malformed postal code; 006 request throttled; 007 invalid query; 008 no results (may include suggestions); 009 latitude/longitude out of range; 010 intersection needs two streets, city and province; 101 ambiguous input (lists possible cities).",
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Three-digit error code"
},
"message": {
"type": "string",
"description": "Human-readable message"
}
},
"required": [
"code",
"message"
],
"additionalProperties": true
}
},
"required": [
"error"
]
}
},
"securitySchemes": {
"authToken": {
"type": "apiKey",
"in": "query",
"name": "auth",
"description": "Auth token (up to 30 bytes) from your geocoder.ca account. Removes the free-tier throttle and draws down credits. Without a token, requests use the throttled free port."
}
}
}
}