Supporting APIs

Every Supporting API endpoint with a cURL, Python and Node sample: supported countries and states, the subcategory catalog, and the publisher sites your plan covers.

The supporting endpoints are the three reference catalogs the rest of the API validates against: which countries and states are supported, which business categories exist, and which publisher directories your plan covers. All three are read-only, unpaginated, and answer with a complete set, so a Read key is enough and caching matters more than pagination.

Endpoints at a glance

List supported countries and states

GET /countries

Returns the complete catalog under data.supportedCountries. Each country carries an ISO code, a base64 id, a numeric databaseId, a hasCity flag, and a states array whose entries have their own ISO codes. A country that is not subdivided returns an empty states array.

Parameters

This endpoint takes none. It always returns the full set.

curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "hasCity": true,        "id": "Q291bnRyeToxMw==",        "iso": "AU",        "name": "Australia",        "states": [          { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" },          { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "hasCity": true,        "id": "Q291bnRyeToxNw==",        "iso": "BE",        "name": "Belgium",        "states": []      }    ]  }}

The two iso fields are what you actually need. A country iso becomes countryIso on create and update, and a state iso becomes stateIso. Validating both against this list before a write turns a server-side 400 into a clear message in your own form.

List subcategories

GET /sub-categories

Returns roughly 6,000 category records under data.subcategories in one unpaginated array. It is the lookup that turns a business type you know as free text into the numeric id a location write demands.

Parameters

None. The whole catalog comes back on every call.

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "subcategories": [      {        "databaseId": 4589,        "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==",        "key": "3d-printing-service",        "name": "3D printing service",        "primary": true      }    ]  }}

Each record carries five fields, and which one you use depends on where it is going.

A location takes one primary category in subCategoryId and up to nine more in additionalCategoryIds.

List plan sites

GET /plan-sites

Returns every publisher directory included in the plan on your account, under data.planSites. This is the authoritative list of numeric site ids, and only ids that appear here are valid elsewhere in the API.

Parameters

None. The response is scoped to your account's plan.

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 184,        "name": "Facebook",        "url": "facebook.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      }    ]  }}

The two country arrays answer different questions. supportedCountries says where the site accepts a listing at all, so filter by your location's countryIso before offering a publisher. hideAddressSupportedCountries says where the site honours a hidden address, which is what a service-area business needs. Both arrays can hold fifty or more codes; the sample above is trimmed.

Site ids are stable and worth knowing: 1 is Google Maps and 184 is Facebook, the two publishers most of the connection flows target.

Place action links

Not an endpoint of its own. Place action links are the Google buttons such as Order online, Reserve a table and Book an appointment, and the platform manages them as a field on the location rather than as a separate resource. You set them through the placeActionLinks array on create and update, and read them back from any location read endpoint.

Each entry needs a placeActionType and a uri, takes an optional isPreferred flag with at most one preferred link per type, and accepts an action of add or delete on update. The valid types, the deletion rules and the sync behaviour are all on Place Action Links.

Errors you will see

None of these endpoints writes, so a Read key never returns SY90016 here. Full list in Error codes.

Next steps

• Look up countries and categories: the task version, with the create-location handoff walked through.
• Add a location: where countryIso and subCategoryId are consumed.
• Find and fix listing errors: uses plan sites to tell a missing publisher from a failing one.
• Supporting APIs reference for the full field list on all three endpoints.