{ "openapi": "3.1.0", "info": { "title": "Pinloft API", "version": "1.0.0", "summary": "Free geocoding API and MCP server: address to latitude/longitude with US Census county, tract and block FIPS codes, districts and reverse geocoding.", "description": "Type an address, get latitude and longitude, a cleaned address and, in the US, the county, Census tract and block FIPS codes from the official US Census geocoder. Worldwide addresses and reverse lookups use OpenStreetMap.\n\nFree tier: 20 calls per minute per IP address. Up to 5 addresses or points per call. Up to 3 OpenStreetMap lookups per call (non-US addresses, US misses, reverse); US addresses use the Census geocoder. About 15 seconds per call at most. Free, no key. OSM results: © OpenStreetMap contributors (ODbL). No key needed. Remote MCP server: https://pinloft.cybermax-tools.workers.dev/mcp", "contact": { "name": "CyberMax", "url": "https://cybermax-tools-cybermax.static.hf.space/" }, "license": { "name": "Proprietary (free to call)", "identifier": "LicenseRef-CyberMax" } }, "servers": [ { "url": "https://pinloft.cybermax-tools.workers.dev" } ], "paths": { "/api/geocode": { "get": { "tags": [ "Pinloft" ], "summary": "Geocode up to 5 addresses (US Census first, OpenStreetMap worldwide)", "description": "US addresses go to the US Census Bureau geocoder (public domain) and come back with county, tract, block group and block FIPS. Other addresses and US misses use OpenStreetMap (Nominatim, Photon fallback). districts=true adds congressional and state legislative districts, place, metro area, school district and ZCTA for US matches.", "operationId": "geocodeAddressesGet", "parameters": [ { "name": "address", "in": "query", "required": true, "description": "Up to 5 addresses separated by | (or repeat the parameter)", "schema": { "type": "string" }, "example": "1600 Pennsylvania Ave NW, Washington, DC 20500" }, { "name": "districts", "in": "query", "required": false, "description": "Add districts for US matches", "schema": { "type": "boolean", "default": false } }, { "name": "country", "in": "query", "required": false, "description": "\"auto\" (default), \"US\" or ISO-2 codes like \"de,at\" to steer non-US lookups", "schema": { "type": "string", "default": "auto" } }, { "name": "language", "in": "query", "required": false, "description": "Language for OpenStreetMap names (default en)", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "results": [ { "id": "1", "query": "233 S Wacker Dr, Chicago, IL 60606", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 41.8789195, "longitude": -87.6366023, "formattedAddress": "233 S WACKER DR, CHICAGO, IL, 60606", "matchType": "exact", "confidence": 1, "houseNumber": "233", "street": "S WACKER DR", "city": "CHICAGO", "county": "Cook County", "state": "Illinois", "stateCode": "IL", "postcode": "60606", "country": "United States", "countryCode": "US", "stateFips": "17", "countyFips": "17031", "tractFips": "17031839100", "blockGroupFips": "170318391002", "blockFips": "170318391002008", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "2", "query": "1600 Pennsylvania Ave NW, Washington, DC 20500", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 38.8987026, "longitude": -77.0351892, "formattedAddress": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500", "matchType": "exact", "confidence": 1, "houseNumber": "1600", "street": "PENNSYLVANIA AVE NW", "city": "WASHINGTON", "county": "District of Columbia", "state": "District of Columbia", "stateCode": "DC", "postcode": "20500", "country": "United States", "countryCode": "US", "stateFips": "11", "countyFips": "11001", "tractFips": "11001980000", "blockGroupFips": "110019800001", "blockFips": "110019800001034", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "3", "query": "10 Downing St, London", "queryType": "address", "status": "matched", "source": "openstreetmap", "latitude": 51.5034878, "longitude": -0.1276965, "formattedAddress": "10 Downing Street, 10, Downing Street, Westminster, Covent Garden, City of Westminster, Greater London, England, SW1A 2AA, United Kingdom", "matchType": "rooftop_or_building", "confidence": 0.9, "houseNumber": "10", "street": "Downing Street", "city": "City of Westminster", "county": null, "state": "England", "stateCode": "ENG", "postcode": "SW1A 2AA", "country": "United Kingdom", "countryCode": "GB", "stateFips": null, "countyFips": null, "tractFips": null, "blockGroupFips": null, "blockFips": null, "osmType": "relation", "osmId": 1879842, "placeType": "office", "districts": null, "attribution": "Data © OpenStreetMap contributors, ODbL 1.0 (openstreetmap.org/copyright); geocoded via Nominatim or Photon", "note": null } ], "count": 3 } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Pinloft" ], "summary": "Geocode up to 5 addresses (US Census first, OpenStreetMap worldwide)", "description": "US addresses go to the US Census Bureau geocoder (public domain) and come back with county, tract, block group and block FIPS. Other addresses and US misses use OpenStreetMap (Nominatim, Photon fallback). districts=true adds congressional and state legislative districts, place, metro area, school district and ZCTA for US matches.", "operationId": "geocodeAddressesPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "description": "Addresses, one per item, e.g. \"1600 Pennsylvania Ave NW, Washington, DC 20500\" or \"10 Downing St, London\". Up to 5." }, "districts": { "type": "boolean" }, "country": { "type": "string" }, "language": { "type": "string" } }, "required": [ "addresses" ] }, "example": { "addresses": [ "233 S Wacker Dr, Chicago, IL 60606", "10 Downing St, London" ], "districts": true } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "results": [ { "id": "1", "query": "233 S Wacker Dr, Chicago, IL 60606", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 41.8789195, "longitude": -87.6366023, "formattedAddress": "233 S WACKER DR, CHICAGO, IL, 60606", "matchType": "exact", "confidence": 1, "houseNumber": "233", "street": "S WACKER DR", "city": "CHICAGO", "county": "Cook County", "state": "Illinois", "stateCode": "IL", "postcode": "60606", "country": "United States", "countryCode": "US", "stateFips": "17", "countyFips": "17031", "tractFips": "17031839100", "blockGroupFips": "170318391002", "blockFips": "170318391002008", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "2", "query": "1600 Pennsylvania Ave NW, Washington, DC 20500", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 38.8987026, "longitude": -77.0351892, "formattedAddress": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500", "matchType": "exact", "confidence": 1, "houseNumber": "1600", "street": "PENNSYLVANIA AVE NW", "city": "WASHINGTON", "county": "District of Columbia", "state": "District of Columbia", "stateCode": "DC", "postcode": "20500", "country": "United States", "countryCode": "US", "stateFips": "11", "countyFips": "11001", "tractFips": "11001980000", "blockGroupFips": "110019800001", "blockFips": "110019800001034", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "3", "query": "10 Downing St, London", "queryType": "address", "status": "matched", "source": "openstreetmap", "latitude": 51.5034878, "longitude": -0.1276965, "formattedAddress": "10 Downing Street, 10, Downing Street, Westminster, Covent Garden, City of Westminster, Greater London, England, SW1A 2AA, United Kingdom", "matchType": "rooftop_or_building", "confidence": 0.9, "houseNumber": "10", "street": "Downing Street", "city": "City of Westminster", "county": null, "state": "England", "stateCode": "ENG", "postcode": "SW1A 2AA", "country": "United Kingdom", "countryCode": "GB", "stateFips": null, "countyFips": null, "tractFips": null, "blockGroupFips": null, "blockFips": null, "osmType": "relation", "osmId": 1879842, "placeType": "office", "districts": null, "attribution": "Data © OpenStreetMap contributors, ODbL 1.0 (openstreetmap.org/copyright); geocoded via Nominatim or Photon", "note": null } ], "count": 3 } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reverse": { "get": { "tags": [ "Pinloft" ], "summary": "Reverse geocode up to 5 points (street address + US FIPS and districts)", "description": "Nearest street address from OpenStreetMap plus, for US points, state/county/tract/block FIPS and districts from the US Census geocoder.", "operationId": "reverseGeocodeGet", "parameters": [ { "name": "lat", "in": "query", "required": false, "description": "Latitude (with lon)", "schema": { "type": "number" }, "example": 40.7484 }, { "name": "lon", "in": "query", "required": false, "description": "Longitude (with lat)", "schema": { "type": "number" }, "example": -73.9857 }, { "name": "coords", "in": "query", "required": false, "description": "Or up to 5 \"lat,lon\" pairs separated by |", "schema": { "type": "string" }, "example": "40.7484,-73.9857|51.5007,-0.1246" } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Pinloft" ], "summary": "Reverse geocode up to 5 points (street address + US FIPS and districts)", "description": "Nearest street address from OpenStreetMap plus, for US points, state/county/tract/block FIPS and districts from the US Census geocoder.", "operationId": "reverseGeocodePost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "coordinates": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "\"lat,lon\" strings" } }, "required": [ "coordinates" ] }, "example": { "coordinates": [ "40.7484,-73.9857", "51.5007,-0.1246" ] } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (see the Retry-After header)", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "retryAfterSeconds": { "type": "integer" }, "limits": { "type": "object" } }, "required": [ "error", "message" ] } } }, "x-mcp-server": "https://pinloft.cybermax-tools.workers.dev/mcp" }